Skip to main content
SMS conversations are stored as SMS-channel call records. Use these endpoints to build inboxes, customer timelines, exports, and conversation cleanup flows. 
Base path: /api/v1/sms-conversations
Authentication uses the standard flexible auth path: API key, JWT bearer token, or dashboard session.

​
Conversation Object

{
  "id": 101,
  "session_id": "sms:+15559876543:+15551234567",
  "assistant_id": 123,
  "assistant_name": "Support Bot",
  "customer_phone_number": "+15559876543",
  "assistant_phone_number": "+15551234567",
  "status": "active",
  "message_count": 8,
  "started_at": "2026-04-30T10:00:00Z",
  "last_activity": "2026-04-30T10:14:00Z",
  "ended_at": null,
  "channel": "sms"
}

​
List Conversations

GET /api/v1/sms-conversations/?skip=0&limit=100&status=active&assistant_id=123
Authorization: Bearer YOUR_TOKEN
Query ParameterTypeDescription
skipintegerRecords to skip
limitintegerRecords to return (1-1000)
statusstringactive or completed
assistant_idintegerFilter by assistant
customer_phonestringFilter by customer phone
date_fromstringISO timestamp lower bound
date_tostringISO timestamp upper bound
Deleted/archived SMS threads are excluded.

​
Get Conversation

GET /api/v1/sms-conversations/{conversation_id}
Authorization: Bearer YOUR_TOKEN
Returns one conversation object or 404.

​
Get Messages

GET /api/v1/sms-conversations/{conversation_id}/messages
Authorization: Bearer YOUR_TOKEN
Response
[
  {
    "id": 1,
    "conversation_id": 101,
    "role": "user",
    "content": "Can I reschedule?",
    "timestamp": "2026-04-30T10:05:00Z",
    "message_index": 1,
    "llm_provider": null,
    "llm_model": null
  },
  {
    "id": 2,
    "conversation_id": 101,
    "role": "assistant",
    "content": "Sure. What day works best?",
    "timestamp": "2026-04-30T10:05:05Z",
    "message_index": 2,
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini"
  }
]

​
Related Conversations

GET /api/v1/sms-conversations/{conversation_id}/related
Authorization: Bearer YOUR_TOKEN
Returns recent related call/SMS records for the same customer and assistant context.
Response
[
  {
    "id": 101,
    "call_sid": "sms_101",
    "channel": "sms",
    "direction": "inbound",
    "status": "active",
    "duration": null,
    "message_count": 8,
    "started_at": "2026-04-30T10:00:00Z",
    "ended_at": null,
    "is_current": true
  }
]

​
Export Conversation

GET /api/v1/sms-conversations/{conversation_id}/export?format=json
Authorization: Bearer YOUR_TOKEN
Supported format values: txt, csv, json. This endpoint returns a file download with Content-Disposition, not a JSON wrapper.

​
Archive Conversation

DELETE /api/v1/sms-conversations/{conversation_id}
Authorization: Bearer YOUR_TOKEN
Archiving an SMS conversation:
  • Marks the SMS call record as deleted via call_meta.sms_deleted.
  • Deletes chat messages for the SMS conversation.
  • Deletes SMS audit and message logs linked to that conversation.
  • Clears related Redis keys on a best-effort basis.
  • Allows future messages between the same numbers to start a fresh conversation.
Response
{
  "success": true,
  "message": "SMS conversation archived successfully"
}

​
SMS Sessions

Session endpoints expose Redis-backed active SMS session state. 
GET /api/v1/sms-sessions/
DELETE /api/v1/sms-sessions/
POST /api/v1/sms-sessions/cleanup
DELETE /api/v1/sms-sessions/{phone_number}/{assistant_id}
GET /api/v1/sms-sessions/ returns:
Response
{
  "success": true,
  "data": {
    "active_sessions": 12,
    "ttl_seconds": 86400
  }
}
DELETE /api/v1/sms-sessions/ clears sessions:
Response
{
  "success": true,
  "message": "SMS sessions cleared",
  "cleared_count": 12
}