Skip to main content
POST
Create a chat session

Custom data

Pass top-level custom_data to store session-level attributes on the new chat session, such as an order ID, cart value, or routing flag. Values can be strings, numbers, or booleans, and are returned by Get Session.
Nested objects are rejected with a 400. To attach contact-level attributes instead, use contact.custom_data on Send Message.
Session custom_data set through this endpoint is stored on the session but is not synced to a connected external ticketing system (e.g. Intercom or HubSpot).

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
contact_id
string<uuid>
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
channel
object
verified
boolean | null
custom_data
object

Session-level custom data to store on the chat session.

contact
object

Contact to associate with the session. When provided (and no contact_id is given) a contact is created/updated and linked to the session; its custom_data is persisted on the contact. Honors the top-level verified flag — verified contacts write to custom_data, otherwise to non_verified_custom_data.

Response

Default Response

id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$