Guest API: Messenger
Conversations with your team, the messenger’s home, pictures and ratings.
| What it does | Route |
|---|---|
| Upload a picture | POST /guest/v1/attachments |
| List the user’s conversations | GET /guest/v1/conversations |
| Start a conversation | POST /guest/v1/conversations |
| Read a conversation | GET /guest/v1/conversations/{conversation_id} |
| Answer the help bot | POST /guest/v1/conversations/{conversation_id}/bot |
| Write in a conversation | POST /guest/v1/conversations/{conversation_id}/messages |
| Rate a conversation | POST /guest/v1/conversations/{conversation_id}/rating |
| Mark a conversation read | POST /guest/v1/conversations/{conversation_id}/read |
| Wait for a reply | GET /guest/v1/conversations/{conversation_id}/wait |
| The messenger’s home | GET /guest/v1/messenger |
Upload a picture
Section titled “Upload a picture”POST /guest/v1/attachments
Asks for somewhere to upload one picture (JPEG, PNG, GIF or WebP) before sending it in a message: put the bytes at the answer’s upload address, then name its id in the message.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Body (application/json): AttachmentBody
| Field | Type | Description |
|---|---|---|
bytes (always) | integer | The picture’s size, at most MaxAttachmentBytes. |
content_type (always) | string | One of AttachmentTypes. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 201 | AttachmentUpload | Made |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 422 | problem | A value that is not right: the problem says which. |
| 429 | problem | Too many requests: wait for Retry-After. |
List the user’s conversations
Section titled “List the user’s conversations”GET /guest/v1/conversations
Newest first, a page at a time: pass the page’s next_before as before for the next one.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
before | query | Where the page starts: the next_before (or before) of the page before it. |
limit | query | How many to answer, at most. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | ConversationPage | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 429 | problem | Too many requests: wait for Retry-After. |
Start a conversation
Section titled “Start a conversation”POST /guest/v1/conversations
Starts a conversation with the user’s first message, or with the help bot’s opening that the messenger’s home offered.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
Idempotency-Key | header | Your own id for this send (at most 100 characters): sent again after a timeout, it is kept once. |
Body (application/json): StartBody
| Field | Type | Description |
|---|---|---|
attachment_ids | array of string | |
button | string | The id of the opening’s button the guest tapped, with no words or pictures; empty when they wrote. |
opening | OpeningRef | The opening the guest was shown when they wrote or tapped; nil for none. |
text (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 201 | Conversation | Made |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 409 | problem | Refused as things stand: the problem says why. |
| 422 | problem | A value that is not right: the problem says which. |
| 429 | problem | Too many requests: wait for Retry-After. |
Read a conversation
Section titled “Read a conversation”GET /guest/v1/conversations/{conversation_id}
The conversation with every part the user may see.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | Conversation | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
Answer the help bot
Section titled “Answer the help bot”POST /guest/v1/conversations/{conversation_id}/bot
The user’s answer to the help bot’s question: a button, or what it asked them to type.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
Body (application/json): BotReplyBody
| Field | Type | Description |
|---|---|---|
button | string | |
part_id (always) | string | |
value | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 201 | Part | Made |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 409 | problem | Refused as things stand: the problem says why. |
| 422 | problem | A value that is not right: the problem says which. |
| 429 | problem | Too many requests: wait for Retry-After. |
Write in a conversation
Section titled “Write in a conversation”POST /guest/v1/conversations/{conversation_id}/messages
Adds the user’s message, with up to four pictures uploaded first.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
Idempotency-Key | header | Your own id for this send (at most 100 characters): sent again after a timeout, it is kept once. |
Body (application/json): MessageBody
| Field | Type | Description |
|---|---|---|
attachment_ids | array of string | Pictures uploaded through an AttachmentUpload and not yet sent. |
text (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 201 | Part | Made |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 409 | problem | Refused as things stand: the problem says why. |
| 422 | problem | A value that is not right: the problem says which. |
| 429 | problem | Too many requests: wait for Retry-After. |
Rate a conversation
Section titled “Rate a conversation”POST /guest/v1/conversations/{conversation_id}/rating
The user’s rating of a closed conversation that asked for one, once.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
Body (application/json): RatingBody
| Field | Type | Description |
|---|---|---|
rating (always) | integer | 1 (bad) to MaxRating (great). |
remark | string | Anything they want to add. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | Part | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 409 | problem | Refused as things stand: the problem says why. |
| 429 | problem | Too many requests: wait for Retry-After. |
Mark a conversation read
Section titled “Mark a conversation read”POST /guest/v1/conversations/{conversation_id}/read
Marks the conversation read up to a part, and answers the user’s unread count.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
Body (application/json): ReadBody
| Field | Type | Description |
|---|---|---|
seq (always) | integer |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | UnreadCount | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
Wait for a reply
Section titled “Wait for a reply”GET /guest/v1/conversations/{conversation_id}/wait
A long poll: answers as soon as the conversation has something newer than after, or after about 25 seconds with nothing new. Ask again straight away while the conversation is on screen.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Parameters
| Name | In | Description |
|---|---|---|
conversation_id (required) | path | The conversation’s id. |
after | query | The version already held: an answer comes only once there is something newer. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | ConversationUpdate | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
The messenger’s home
Section titled “The messenger’s home”GET /guest/v1/messenger
What the messenger’s first screen shows this user: the greeting, the team’s faces and reply time, the cards your team published, open conversations, a few articles and tickets, and the help bot’s opening when one would start.
Needs: the app key (X-CRM-App-Key) and the signed-in user’s token (Authorization: Bearer …), or their id for an app with unverified sign-in. See From a website or web app.
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | MessengerHome | OK |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 403 | problem | Refused: the app is switched off, or this is not allowed. |
| 429 | problem | Too many requests: wait for Retry-After. |