Skip to content

HTTP API

GET /sdk/v1/config

The app’s look, languages and screenshot mode

Sent with: accept-language, X-App-Key, origin

Answers: 200

GET /sdk/v1/design/bundle

The app’s design: its theme, components and templates (ETag)

Sent with: if-none-match, X-App-Key, origin

Answers: 200, 304

POST /sdk/v1/tickets

Send a contact message: payload (JSON) and at most one screenshot

Sent with: X-App-Install, X-App-Key, origin, X-User-Token

Body

Field Type Required
payload string yes
screenshot string

Answers: 201

POST /sdk/v1/answers

Ask the app’s help assistant: grounded in its help content, or silent

Sent with: X-App-Install, X-App-Key, origin

Body

Field Type Required
question string yes
history Turn[]
language en · ar
flows boolean

Answers: 200

GET /sdk/v1/conversations

The user’s conversations, newest first

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

GET /sdk/v1/conversations/{conversation_id}

One conversation’s messages

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

POST /sdk/v1/conversations/{conversation_id}/messages

Write in a conversation; a closed one reopens

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Body

Field Type Required
text string yes

Answers: 201

POST /sdk/v1/conversations/{conversation_id}/attachments

Send an image (a PNG or a JPEG), with words or without

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Body

Field Type Required
file string yes
text string

Answers: 201

POST /sdk/v1/conversations/{conversation_id}/typing

The user is typing: the team sees it for a few seconds (send at most every 3 s)

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Answers: 204

POST /sdk/v1/conversations/{conversation_id}/seen

The user has read the conversation up to a message: its unread count drops

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Body

Field Type Required
message_id string (uuid)

Answers: 204

GET /sdk/v1/unread

The user’s unread messages: the launcher’s badge

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

GET /sdk/v1/attachments/{attachment_id}

An image of a conversation, through the signed link a message carries

Answers: 200

POST /sdk/v1/callbacks

Ask the team to call back: a number, what it’s about, and when suits

Sent with: X-App-Install, X-App-Key, origin, X-User-Token

Body

Field Type Required
phone string yes
note string yes
preferred_at string (date-time)
user_id string
language en · ar

Answers: 201

GET /sdk/v1/home

The messenger’s home: greeting, team, help center, latest

Sent with: accept-language, X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

GET /sdk/v1/articles

The app’s help articles: a collection’s, or those matching q

Sent with: accept-language, X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

GET /sdk/v1/articles/{article_id}

One help article, to read in the messenger

Sent with: X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

GET /sdk/v1/events

The user’s conversations as they happen (server-sent events; read with a streaming fetch, since it needs the app key)

Sent with: Last-Event-ID, X-App-Key, origin, X-App-Install, X-User-Token

Answers: 200

Every SDK sends the person’s identity, events and consent here, with the same publishable key.

POST /sdk/v1/identify

Who the app’s user is; email and phone are hashed on arrival

Sent with: X-User-Hash, X-App-Install, X-App-Key

Body

Field Type Required
external_id string
email string
phone string
email_sha256 string
phone_sha256 string
attributes object

Answers: 200

POST /sdk/v1/events

What the identified user did

Sent with: X-User-Hash, X-App-Key

Body

Field Type Required
external_id string yes
events EventIn[] yes

Answers: 200

PUT /sdk/v1/consent

What the user agreed to, per channel

Sent with: X-User-Hash, X-App-Key

Body

Field Type Required
external_id string yes
channel push · in_app · email · whatsapp · sms · telegram yes
granted boolean yes
occurred_at string (date-time)

Answers: 200

POST /sdk/v1/install/events

What the app’s user did before the app identified them

Sent with: X-App-Install, X-App-Key

Body

Field Type Required
events EventIn[] yes

Answers: 200

PUT /sdk/v1/install/consent

What the app’s user agreed to before the app identified them

Sent with: X-App-Install, X-App-Key

Body

Field Type Required
channel push · in_app · email · whatsapp · sms · telegram yes
granted boolean yes
occurred_at string (date-time)

Answers: 200

POST /server/v1/identify

Create or update a profile by the match rule

Sent with: authorization

Body

Field Type Required
external_id string
email string
phone string
email_sha256 string
phone_sha256 string
attributes object

Answers: 200

POST /server/v1/events

Events, each naming its person

Sent with: authorization

Body

Field Type Required
events ServerEventIn[] yes

Answers: 200

POST /server/v1/orders

Orders; one sent again by its order_id is updated

Sent with: authorization

Body

Field Type Required
orders OrderIn[] yes

Answers: 200

PUT /server/v1/consent

What a person agreed to, per channel

Sent with: authorization

Body

Field Type Required
external_id string yes
channel push · in_app · email · whatsapp · sms · telegram yes
granted boolean yes
occurred_at string (date-time)

Answers: 200

POST /server/v1/import

A batch of end users as text/csv or application/json (at most 10,000 rows)

Sent with: authorization

Answers: 200

GET /server/v1/profiles/{external_id}

A person, by the org’s external id

Sent with: authorization

Answers: 200

DELETE /server/v1/profiles/{external_id}

Delete a person and everything about them; every service forgets them too

Sent with: authorization

Answers: 204