SMS API Reference

Complete API documentation for SMS system endpoints.

Authentication

All endpoints require authentication via JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Base URL

https://yourdomain.com/api/sms

Endpoints

Conversations

Start SMS Conversation

POST /api/sms/conversations/start

Creates a new SMS conversation or resumes an existing one.

Request Body:

{
  "phone_number": "+14165551234",
  "message": "Hello! How can I help you?",
  "contact_name": "John Doe",
  "contact_company": "Acme Corp",
  "assistant_id": "asst-123"
}

Response: 201 Created

{
  "success": true,
  "conversation_id": "conv-456",
  "message_id": "msg-789",
  "is_new_conversation": true
}

Error Responses:

• 400 - Missing phone_number or message, invalid format
• 429 - Usage limit exceeded
• 500 - Server error

Send Message

POST /api/sms/conversations/:conversationId/messages

Sends a message in an existing conversation.

Request Body:

{
  "message": "Thanks for reaching out!"
}

Response: 200 OK

{
  "success": true,
  "message_id": "msg-789"
}

Error Responses:

• 400 - Missing message or conversation ID
• 404 - Conversation not found
• 500 - Server error

List Conversations

GET /api/sms/conversations?limit=50&offset=0

Retrieves SMS conversations for the tenant.

Query Parameters:

• limit (optional, default: 50) - Maximum number of conversations
• offset (optional, default: 0) - Number of conversations to skip

Response: 200 OK

{
  "conversations": [
    {
      "id": "conv-456",
      "channel": "sms",
      "channel_identifier": "+14165551234",
      "contact_data": {
        "name": "John Doe",
        "company": "Acme Corp",
        "phone": "+14165551234"
      },
      "started_at": "2024-01-15T10:00:00Z",
      "last_message_at": "2024-01-15T10:05:00Z"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Update AI Guide

PUT /api/sms/conversations/:conversationId/ai-guide

Updates the AI conversation guide for a conversation.

Request Body:

{
  "ai_guide": "This customer is interested in enterprise plans. Focus on ROI and scalability."
}

Response: 200 OK

{
  "success": true,
  "conversation_id": "conv-456"
}

Campaigns

List Campaigns

GET /api/sms/campaigns

Retrieves all SMS campaigns for the tenant.

Response: 200 OK

{
  "campaigns": [
    {
      "id": "camp-123",
      "name": "Spring Promotion",
      "message": "Hi {name}, special offer for {company}!",
      "status": "draft",
      "total_recipients": 100,
      "sent_count": 0,
      "failed_count": 0,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Campaign

POST /api/sms/campaigns

Creates a new SMS campaign.

Request Body:

{
  "name": "Spring Promotion",
  "message": "Hi {name}, special offer for {company}!",
  "workflow_config": {
    "steps": []
  }
}

Response: 201 Created

{
  "campaign": {
    "id": "camp-123",
    "name": "Spring Promotion",
    "message_template": "Hi {name}, special offer for {company}!",
    "status": "draft",
    "total_recipients": 0,
    "sent_count": 0,
    "failed_count": 0
  }
}

Update Campaign

PUT /api/sms/campaigns/:campaignId

Updates a campaign (draft status only).

Request Body:

{
  "name": "Updated Campaign Name",
  "message": "New message template",
  "workflow_config": {
    "steps": []
  },
  "status": "draft"
}

Response: 200 OK

{
  "campaign": {
    "id": "camp-123",
    "name": "Updated Campaign Name",
    "message_template": "New message template",
    "status": "draft"
  }
}

Send Campaign

POST /api/sms/campaigns/:campaignId/send

Sends a campaign to all recipients.

Response: 200 OK

{
  "success": true,
  "sentCount": 95,
  "failedCount": 5,
  "totalRecipients": 100
}

Error Responses:

• 400 - Campaign already sent or no phone number configured
• 404 - Campaign not found
• 500 - Server error

Get Recipients

GET /api/sms/campaigns/:campaignId/recipients

Retrieves recipients for a campaign.

Response: 200 OK

{
  "recipients": [
    {
      "id": "recip-123",
      "phone_number": "+14165551234",
      "name": "John Doe",
      "company": "Acme Corp",
      "status": "pending"
    }
  ]
}

Add Recipients

POST /api/sms/campaigns/:campaignId/recipients

Adds recipients to a campaign.

Request Body:

{
  "recipients": [
    {
      "phone_number": "+14165551234",
      "name": "John Doe",
      "company": "Acme Corp"
    }
  ]
}

Response: 200 OK

{
  "success": true,
  "added": 1
}

Import CSV

POST /api/sms/campaigns/:campaignId/import-csv
Content-Type: multipart/form-data

Imports recipients from a CSV file.

Request:

• file - CSV file (max 5MB)

Response: 200 OK

{
  "success": true,
  "imported": 95,
  "errors": 5,
  "errorDetails": [
    {
      "row": 3,
      "error": "Missing phone number"
    }
  ],
  "totalRows": 100
}

Get Campaign Status

GET /api/sms/campaigns/:campaignId/status

Retrieves campaign status and recipient breakdown.

Response: 200 OK

{
  "campaign": {
    "id": "camp-123",
    "name": "Spring Promotion",
    "status": "completed",
    "total_recipients": 100,
    "sent_count": 95,
    "failed_count": 5,
    "started_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:15:00Z"
  },
  "statusCounts": {
    "sent": 95,
    "failed": 5,
    "pending": 0
  }
}

Webhooks

Telnyx SMS Webhook

POST /api/webhooks/telnyx/sms

Receives inbound SMS messages and status updates from Telnyx.

Headers:

• X-Telnyx-Signature - HMAC signature (if verification enabled)

Request Body:

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "id": "msg-123",
      "from": {
        "phone_number": "+14165551234"
      },
      "to": {
        "phone_number": "+14165559999"
      },
      "text": "Hello!",
      "direction": "inbound",
      "received_at": "2024-01-15T10:00:00Z"
    }
  }
}

Response: 200 OK

{
  "received": true
}

Error Codes

Client Errors (4xx)

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Missing or invalid authentication
• 404 Not Found - Resource not found
• 429 Too Many Requests - Usage limit exceeded

Server Errors (5xx)

• 500 Internal Server Error - Server error

Rate Limiting

• Campaign sending: 100ms delay between messages
• API requests: Standard rate limits apply
• Webhook processing: No rate limits (handled by Telnyx)

Related Documentation

• Conversations Guide - Using conversations
• Campaigns Guide - Managing campaigns
• Troubleshooting - Error resolution