Copy page

Start Here

🚀 Quick Start Guide

Welcome to the Tech231 Platform! This guide will help you get started with sending SMS messages through our platform quickly and easily.

📋 What You'll Need

Before you begin, make sure you have:

• An active Tech231 Platform account
• Your Zitadel OAuth2 credentials (Client ID and Client Secret)
• A registered sender ID (we'll help you get one if needed)

🔐 Authentication

The Tech231 Platform uses Zitadel OAuth2 authentication with JWT tokens for secure access. Your tenant context is automatically determined from the resource scope in your access token - no need for additional headers!

Authentication Types

We support two authentication methods:

1. Service Account Authentication (Recommended for API Integration)

Service accounts are ideal for server-to-server communication and automated systems.

Getting Your Service Account Credentials:

1. Log in to your Tech231 Platform dashboard
2. Navigate to Settings → Service Accounts
3. Click "Create Service Account"
4. Copy your:
   • Client ID: Your service account identifier
   • Client Secret: Your service account password (store securely!)
   • Token Endpoint: https://auth.tech231apps.net/oauth/v2/token

2. User Account Authentication (For Dashboard and User Applications)

User accounts are for individual users accessing the platform through web or mobile applications.

Obtaining an Access Token

Service Account Token (Client Credentials Flow)

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud"

Response:

Code
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud"
}

User Account Token (Authorization Code Flow)

For user-based applications, implement the OAuth2 Authorization Code flow:

1. Redirect user to authorization endpoint:

Code
https://auth.tech231apps.net/oauth/v2/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK_URL
  &response_type=code
  &scope=openid email profile offline_access urn:zitadel:iam:org:project:id:321914919689650215:aud

2. Exchange authorization code for token:

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_CALLBACK_URL"

Using Your Access Token

Include the JWT access token in the Authorization header for all API requests:

Code
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Important: Your tenant context is embedded in the JWT token's resource scope. No additional tenant headers are needed!

Token Refresh

Access tokens expire after 1 hour. For long-running applications:

With Refresh Token:

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Without Refresh Token (Service Accounts):

Simply request a new token using client credentials when the current one expires.

Required OAuth2 Scopes

Make sure to request these scopes for full platform access:

• openid - OpenID Connect authentication
• email - User email access
• profile - User profile information
• offline_access - Refresh token (for user accounts)
• urn:zitadel:iam:org:project:id:321914919689650215:aud - Platform resource scope
• urn:zitadel:iam:user:resourceowner - Resource owner information

📱 Getting a Sender ID

A Sender ID is what your recipients see as the sender of your SMS messages. You have several options:

Types of Sender IDs

• Alphanumeric: Custom text (e.g., "YourCompany", "ALERTS") - up to 11 characters
• Shortcode: Dedicated numbers for two-way messaging
• Shared Shortcode: Cost-effective option with keyword routing

Requesting a Sender ID

1. Navigate to Sender IDs in your dashboard
2. Click "Request New Sender ID"
3. Choose your sender ID type and enter your preferred ID
4. Submit your request with business justification
5. Wait for approval (typically 1-2 business days)

Tip: Pre-approved sender IDs like your company name are processed faster!

🚀 Sending SMS

Once you have your access token and an approved sender ID, you can start sending messages.

We support both Transactional (single message) and Bulk (batch) sending flows.

For detailed instructions and API examples, please refer to our SMS Sending Flows Guide.

🔔 Receiving SMS Messages (Inbound Webhooks)

To receive SMS messages sent to your shortcodes, you need to implement a webhook endpoint.

Webhook Setup

1. Navigate to Settings → Webhooks in your dashboard
2. Add your webhook URL (must be HTTPS)
3. Configure authentication (we recommend HMAC signature verification)
4. Select events you want to receive (e.g., sms.received)
5. Test your webhook with our testing tool

Implementing Your Webhook Endpoint

Your webhook must accept POST requests with the following payload:

Code
{
  "eventType": "sms.received",
  "eventId": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_inbound_123456",
    "from": "+1234567890",
    "to": "12345",
    "message": "KEYWORD some user message",
    "receivedAt": "2024-01-15T10:30:00Z",
    "keyword": "KEYWORD",
    "shortcode": "12345",
    "carrier": "T-Mobile"
  }
}

Example webhook implementation (Node.js):

Code
const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

// Verify webhook signature
function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.post('/webhooks/sms-inbound', (req, res) => {
  // Verify signature from header
  const signature = req.headers['x-tech231-signature'];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const { eventType, data } = req.body;
  
  if (eventType === 'sms.received') {
    console.log(`Received SMS from ${data.from}: ${data.message}`);
    
    // Process the inbound message
    // Your business logic here
    
    // Respond quickly to acknowledge receipt
    res.status(200).json({ received: true });
  }
});

app.listen(3000);

Best practices for webhooks:

• Respond quickly: Return 200 OK within 5 seconds
• Process asynchronously: Queue messages for background processing
• Implement retries: We'll retry failed webhooks up to 3 times
• Verify signatures: Always validate the x-tech231-signature header
• Handle duplicates: Use eventId to detect duplicate deliveries

For detailed webhook specifications, see our Inbound SMS Webhook Documentation.

🛡️ Best Practices

Authentication & Security

• Never expose credentials: Use environment variables for client secrets
• Store tokens securely: Use secure storage for access tokens
• Implement token refresh: Handle expired tokens gracefully
• Use HTTPS only: All API requests must use HTTPS
• Rotate secrets regularly: Change service account credentials periodically

Message Content

• Keep messages concise and clear
• Include opt-out instructions for marketing messages
• Avoid special characters that might not display properly
• Test messages before sending to large audiences

Rate Limits

• Respect API rate limits (check your plan details)
• Implement exponential backoff for retries
• Monitor your usage in the dashboard
• Request rate limit increases if needed

📞 Need Help?

Quick Troubleshooting

Authentication Errors (401)

• Verify your client credentials are correct
• Check that your access token hasn't expired
• Ensure you're requesting the correct scopes
• Verify the token endpoint URL is correct

Forbidden Errors (403)

• Check your service account has the necessary permissions
• Verify your resource scope includes the platform audience
• Contact support to review your account permissions

Sender ID Issues

• Confirm your sender ID is approved and active
• Check spelling and format (alphanumeric IDs are case-sensitive)
• Verify your sender ID hasn't expired

Message Delivery Issues

• Check recipient number format (include country code)
• Verify the recipient's carrier supports your message type
• Check our status page for service issues

Support Resources

• 📚 API Reference: Complete endpoint documentation with examples
• 💬 Support Chat: Available in your dashboard
• 📧 Email Support: support@tech231apps.net
• 📞 Phone Support: Available for premium plans

Next Steps

Now that you're sending messages successfully:

1. Explore the API Reference for advanced features
2. Set up webhooks for inbound messages and delivery notifications
3. Configure sender ID pools for high-volume sending
4. Review analytics in your dashboard to optimize messaging
5. Implement error handling and retry logic in your application

Happy messaging! 🎉