Customer chat sessions

Keep the service key on your backend. Issue a short-lived contact session when a signed-in customer needs to read their conversations or submit messages from your application.

With contact_sessions:write, call POST /api/v2/contact-sessions:

123456{
  "contact_id": "ctc_your_contact",
  "conversation_ids": ["con_your_conversation"],
  "permissions": ["conversations:read", "messages:read", "customer_messages:write", "media:read", "media:write"],
  "expires_in_seconds": 900
}

Every conversation must belong to the contact and an explicitly granted inbox. Permissions cannot exceed the issuing key. Lifetimes range from 60 to 3,600 seconds. Store the returned token in the customer session and use it as a bearer credential.

A session can read only its granted conversations, messages, and attachments. It cannot read notes, send staff replies, transfer ownership, or manage keys, calls, and webhooks.

On API and website chat connections, use the session token with POST /api/v2/conversations/{conversation_id}/customer-messages:

1{ "content": [{ "type": "text", "text": "Hello, I have a question." }] }

Include a unique Idempotency-Key for each logical message. This route creates an incoming message in the same conversation the support team sees. It cannot fabricate WhatsApp, email, or other provider-origin messages.

Your backend revokes a session with DELETE /api/v2/contact-sessions/{session_id}. Expiry, account suspension, application disablement, and revocation of the issuing key also stop API access. Refresh by issuing a new session rather than extending a previously returned token.

Grant media:write when customers need to upload files. The session can call POST /api/v2/media with multipart data and use the returned media_id in a customer message. Standalone uploads are bound to that session and its granted inboxes. Another customer's session cannot access them. Once sent, attachments are visible only through the authorized conversation.