Conversations

Conversations represent 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.

The channel field on each message tells you how it was delivered. Your code works the same across channels — the differences are in what features are available.

In this guide

• Channel behavior: SMS/MMS vs iMessage capabilities, media, and reactions
• API reference: list/get/update conversations and list conversation messages
• Webhook behavior: see Webhooks for event payloads

SMS vs iMessage

SMS

Standard text messaging over the cellular network. Works with any phone number.

• Outbound requires 10DLC registration (carrier requirement for US numbers)
• Inbound works immediately — no registration needed
• Images arrive as MMS (channel: "mms")

iMessage

Apple’s messaging protocol. Delivered over the internet to Apple devices, with automatic SMS fallback for non-Apple recipients.

• No 10DLC registration required
• Supports reactions (tapbacks), rich media, and image carousels
• channel is "imessage" for messages delivered via iMessage

Capabilities

API reference

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.ai/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.ai/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.ai/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.ai/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
      "channel": "sms",
10
      "mediaUrl": null,
11
      "receivedAt": "2025-01-15T11:30:00Z"
12
    }
13
  ],
14
  "hasMore": true
15
}

Message fields

Media

When someone sends an image, video, or file, the message includes a mediaUrl pointing to the hosted media. The body may be empty if only media was sent.

1
{
2
  "id": "msg_002",
3
  "body": "",
4
  "fromNumber": "+15559876543",
5
  "toNumber": "+15551234567",
6
  "direction": "inbound",
7
  "channel": "imessage",
8
  "mediaUrl": "https://storage.googleapis.com/inbound-file-store/abc123_IMG_5414.png",
9
  "receivedAt": "2025-01-15T12:01:00Z"
10
}

Image carousels (multiple images sent at once) arrive as separate messages, each with its own mediaUrl.

Media works on both iMessage and MMS (SMS with images). When an image arrives via SMS, the channel is "mms".

Reactions

iMessage supports tapback reactions — the emoji responses users can add to individual messages (heart, thumbs up, etc.). Reactions are only available on iMessage channels.

Send a reaction

POST /v1/messages/{message_id}/reactions

$
curl -X POST "https://api.agentphone.ai/v1/messages/msg_001/reactions" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"reaction": "love"}'

1
{
2
  "id": "rxn_abc123",
3
  "reactionType": "love",
4
  "messageId": "msg_001",
5
  "channel": "imessage"
6
}

Reacting to an image in a carousel works the same way — use the message ID of the specific image.

Receive reactions

When someone reacts to a message your agent sent, an agent.reaction webhook event is fired. See Webhooks for the payload format.

Typing indicator

Show a typing bubble in an iMessage conversation. This signals to the recipient that your agent is composing a response.

POST /v1/conversations/{conversation_id}/typing

The request body is empty. The indicator auto-expires after a few seconds, so there’s no “stop typing” call needed. Send it right before your agent starts generating a response.

$
curl -X POST "https://api.agentphone.ai/v1/conversations/conv_def456/typing" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{}'

1
{
2
  "conversationId": "conv_def456",
3
  "channel": "iMessage",
4
  "status": "typing indicator sent"
5
}