Skip to main content

​
Conversations Endpoint

Work with customer conversations (chats, emails, calls, etc.) through the API.

​
List Conversations

Get all conversations for a sub-account. Endpoint: 
GET /conversations
Parameters:
ParameterTypeRequiredDescription
limitnumberNoMax results (default: 25, max: 100)
offsetnumberNoSkip first N results (for pagination)
channelstringNoFilter by channel: sms, email, instagram, facebook, whatsapp, voice
statusstringNoFilter by status: open, closed, resolved
customer_idstringNoFilter by customer ID
Request: 
curl -X GET "https://api.agentclara.app/conversations?limit=25&channel=sms" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "data": [
    {
      "id": "conv_abc123",
      "customer_id": "cust_xyz789",
      "customer_name": "John Smith",
      "customer_email": "john@example.com",
      "customer_phone": "+15551234567",
      "channel": "sms",
      "subject": "Appointment Question",
      "last_message": "Can I move my appointment to Friday?",
      "timestamp": "2024-03-15T10:30:00Z",
      "status": "open",
      "unread": true
    }
  ]
}

​
Get Single Conversation

Get details about one conversation. Endpoint: 
GET /conversations/{conversation_id}
Parameters:
ParameterTypeRequiredDescription
conversation_idstringYesThe conversation ID
Request: 
curl -X GET "https://api.agentclara.app/conversations/conv_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "data": {
    "id": "conv_abc123",
    "customer_id": "cust_xyz789",
    "customer_name": "John Smith",
    "customer_phone": "+15551234567",
    "channel": "sms",
    "status": "open",
    "messages": [
      {
        "id": "msg_1",
        "sender": "customer",
        "content": "Can I reschedule my appointment?",
        "timestamp": "2024-03-15T10:30:00Z"
      },
      {
        "id": "msg_2",
        "sender": "assistant",
        "content": "Of course! What date works better?",
        "timestamp": "2024-03-15T10:31:00Z"
      }
    ]
  }
}

​
Create Conversation

Start a new conversation programmatically. Endpoint: 
POST /conversations
Body Parameters:
ParameterTypeRequiredDescription
customer_phonestringConditionalPhone number (if channel is SMS or voice)
customer_emailstringConditionalEmail (if channel is email)
customer_namestringNoCustomer’s name
channelstringYessms, email, voice, etc.
messagestringNoInitial message content
Request: 
curl -X POST "https://api.agentclara.app/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "+15551234567",
    "customer_name": "John Smith",
    "channel": "sms",
    "message": "Hi John, checking in on your appointment!"
  }'
Response: 
{
  "success": true,
  "data": {
    "id": "conv_abc123",
    "customer_phone": "+15551234567",
    "customer_name": "John Smith",
    "channel": "sms",
    "status": "open",
    "message_id": "msg_123"
  }
}

​
Send Message

Send a message in an existing conversation. Endpoint: 
POST /conversations/{conversation_id}/messages
Body Parameters:
ParameterTypeRequiredDescription
contentstringYesMessage text
senderstringNocustomer or assistant (default: assistant)
Request: 
curl -X POST "https://api.agentclara.app/conversations/conv_abc123/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Perfect! I have you down for Friday at 2pm."
  }'
Response: 
{
  "success": true,
  "data": {
    "message_id": "msg_456",
    "conversation_id": "conv_abc123",
    "content": "Perfect! I have you down for Friday at 2pm.",
    "sender": "assistant",
    "timestamp": "2024-03-15T10:35:00Z"
  }
}

​
Update Conversation

Change conversation status or metadata. Endpoint: 
PATCH /conversations/{conversation_id}
Body Parameters:
ParameterTypeRequiredDescription
statusstringNoopen, closed, or resolved
customer_namestringNoUpdate customer name
tagsarrayNoAdd tags: ["important", "vip"]
Request: 
curl -X PATCH "https://api.agentclara.app/conversations/conv_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "tags": ["completed", "satisfied"]
  }'
Response: 
{
  "success": true,
  "data": {
    "id": "conv_abc123",
    "status": "resolved",
    "tags": ["completed", "satisfied"]
  }
}

​
Close Conversation

Mark a conversation as resolved/closed. Endpoint: 
POST /conversations/{conversation_id}/close
Request: 
curl -X POST "https://api.agentclara.app/conversations/conv_abc123/close" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "data": {
    "id": "conv_abc123",
    "status": "closed",
    "closed_at": "2024-03-15T11:00:00Z"
  }
}

​
Conversation Fields

FieldTypeDescription
idstringUnique conversation ID
customer_idstringAssociated customer ID
customer_namestringCustomer’s name
customer_emailstringCustomer’s email
customer_phonestringCustomer’s phone number
channelstringCommunication channel
statusstringopen, closed, resolved
subjectstringConversation title/subject
last_messagestringMost recent message
timestampISO 8601When conversation started
unreadbooleanHas unread messages?
tagsarrayCustomer tags
messagesarrayMessage thread

​
Examples

​
List All SMS Conversations

curl -X GET "https://api.agentclara.app/conversations?channel=sms&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get Unread Conversations

curl -X GET "https://api.agentclara.app/conversations?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create and Send Message

# 1. Create conversation
curl -X POST "https://api.agentclara.app/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "+15551234567",
    "channel": "sms"
  }'

# 2. Send message (use conv_id from response)
curl -X POST "https://api.agentclara.app/conversations/conv_abc123/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi! How can we help?"
  }'

​
Error Responses

400 - Bad Request: 
{
  "success": false,
  "error": "Missing required field: customer_phone"
}
404 - Not Found: 
{
  "success": false,
  "error": "Conversation not found"
}
401 - Unauthorized: 
{
  "success": false,
  "error": "Invalid API key"
}

​
Next Steps

Questions? Email support@agentclara.ai