Conversations

Conversations represent SMS message threads between your agent’s phone number and an external participant. Each conversation tracks the full message history, supports custom metadata for storing session state, and is sorted by most recent activity.

List conversations

List all conversations for this project, sorted by most recent activity.

GET /v1/conversations

Query parameters

Example

$
curl -X GET "https://api.agentphone.to/v1/conversations?limit=10&offset=0" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "id": "conv_def456",
5
      "agentId": "agt_abc123",
6
      "phoneNumberId": "num_xyz789",
7
      "phoneNumber": "+15551234567",
8
      "participant": "+15559876543",
9
      "lastMessageAt": "2025-01-15T12:00:00Z",
10
      "lastMessagePreview": "Thanks for your help!",
11
      "messageCount": 8,
12
      "metadata": {
13
        "customerName": "Jane Doe",
14
        "orderId": "ORD-12345"
15
      },
16
      "createdAt": "2025-01-15T11:30:00Z"
17
    }
18
  ],
19
  "hasMore": false,
20
  "total": 1
21
}

Get conversation

Get a conversation with its recent messages.

GET /v1/conversations/{conversation_id}

Query parameters

Example

$
curl -X GET "https://api.agentphone.to/v1/conversations/conv_def456?message_limit=20" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Update conversation

Update conversation metadata (state). Use this to store custom context for AI agents, such as customer information, business context, or session state.

The metadata is included in webhook payloads as conversationState, enabling your AI backend to maintain context across messages.

PATCH /v1/conversations/{conversation_id}

Request body

Example

$
curl -X PATCH "https://api.agentphone.to/v1/conversations/conv_def456" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "metadata": {
>
      "customerName": "Jane Doe",
>
      "orderId": "ORD-12345",
>
      "topic": "order_tracking",
>
      "resolved": false
>
    }
>
  }'

Get conversation messages

Get paginated messages for a conversation. Use before/after for cursor-based pagination through large message histories.

GET /v1/conversations/{conversation_id}/messages

Query parameters

Example

$
curl -X GET "https://api.agentphone.to/v1/conversations/conv_def456/messages?limit=20" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "id": "msg_001",
5
      "body": "Hi, I need help with my order",
6
      "fromNumber": "+15559876543",
7
      "toNumber": "+15551234567",
8
      "direction": "inbound",
9
      "receivedAt": "2025-01-15T11:30:00Z"
10
    }
11
  ],
12
  "hasMore": true
13
}