Chats: text conversations with the same agent

A chat is a text conversation with one of your voice agents. The agent definition is shared — same prompt, same voice (irrelevant for chat), same knowledge base, same functions. The channel layer changes; the brain doesn't.

Two ways to use chat

The widget is the fast path. The API is the right path when you have a custom client.

REST API

Start a chat

Copycurl -X POST https://api.call2me.app/v1/chats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "metadata": { "user_id": "u_4521", "source": "support-page" }
  }'

Returns 200 with the session object. Keep its session_id (chat_...) for subsequent messages.

Send a message

Copycurl -X POST https://api.call2me.app/v1/chats/chat_xyz789/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Where is my order 4521?"
  }'

Returns both stored messages:

Copy{
  "user_message": { "message_id": "msg_abc123", "role": "user", "content": "Where is my order 4521?", "cost_usd": 0, "created_at": "..." },
  "assistant_message": { "message_id": "msg_def456", "role": "assistant", "content": "Your order shipped yesterday and arrives Thursday.", "cost_usd": 0.012, "created_at": "..." }
}

Streaming responses (SSE)

For typing-indicator UX, add "stream": true to the same send-message call. The response is a text/event-stream (Server-Sent Events):

Copycurl -N -X POST https://api.call2me.app/v1/chats/chat_xyz789/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Where is my order?", "stream": true }'

Each line is a data: event. Delta chunks stream the answer token by token, then a final done event carries the message id and cost:

Copydata: {"delta": "Your order "}

data: {"delta": "shipped yesterday."}

data: {"done": true, "message_id": "msg_def456", "cost_usd": 0.012}

data: [DONE]

Concatenate the delta values to rebuild the full reply. Without stream, the same endpoint returns the completed { user_message, assistant_message } object. Works with both sk_ keys and ephemeral end-user tokens.

Fetching history

Copycurl https://api.call2me.app/v1/chats/chat_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is the session object with a messages array (GET .../messages is not supported; it only accepts POST).

Pricing

Chat is billed $0.01 per message, where one message is a user input plus the agent's reply (one pair). Function calls don't add a separate charge; they're part of the message that triggered them.

A typical 10-message support exchange costs about $0.10. The same conversation as a voice call would cost roughly $0.50 (5 minutes × $0.10/min voice base, plus telephony if applicable).

Knowledge base & functions

Both work the same way as voice:

• Knowledge base: agent retrieves relevant chunks before responding
• Functions: LLM decides to invoke; platform calls your endpoint; result lands in the next message

The agent doesn't know whether the user is on a phone or in a browser — the channel is invisible to the prompt.

Widget vs. API: when to pick which

Pick the widget when:

• You want chat on your marketing site, fast
• You're fine with the platform's UI (customizable but bounded)
• The user is anonymous (or you'll capture identity inside the chat)

Pick the API when:

• You're building a logged-in product UI with your own design system
• You need to inject context (metadata.user_id) per session
• Mobile app, desktop app, or backend-to-backend chat

What's next

• Widgets — the embedded chat widget
• Agents — the shared agent definition
• Functions — tool calls inside chats