Guest API: In-app messages
The check-in that brings in-app messages, receipts, and survey answers.
| What it does | Route |
|---|---|
| Declare the app’s places | PUT /guest/v1/app-links |
| Check in | POST /guest/v1/checkin |
| Open a message by its link | POST /guest/v1/messages/{message_id}/open |
| Say what the user did with a message | POST /guest/v1/receipts |
| Answer a survey’s question | POST /guest/v1/surveys/{message_id}/answers |
| Finish a survey | POST /guest/v1/surveys/{message_id}/submit |
Declare the app’s places
Section titled “Declare the app’s places”PUT /guest/v1/app-links
The places in the app a link may go, sent once a build when a check-in asks for them, so your team can pick them in the link picker.
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): AppLinksReport
| Field | Type | Description |
|---|---|---|
app_version (always) | string | |
digest (always) | string | |
links (always) | array of DeclaredLink |
Answers
| Status | Body | Meaning |
|---|---|---|
| 204 | none | Done, with nothing to say |
| 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. |
Check in
Section titled “Check in”POST /guest/v1/checkin
Says the app is open (its screen, version and time zone) and answers the in-app messages waiting for this user, with their unread counts. Check in when the user signs in, when the app comes to the front, and after sending events; one sooner than 20 seconds after the last is answered from it.
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): CheckinBody
| Field | Type | Description |
|---|---|---|
app_version (always) | string | |
holds_for_screens | boolean | Says the app holds a message meant for some screens (InAppMessage.Screens) until one of them is on: an SDK that knows how, whose host has named a screen this run. A message for some screens is never answered to an app that does not say so. |
links_digest | string | LinksDigest of the destinations the app declares, when it declares any: a check-in answers SendLinks for one PurrCRM has not been sent. |
platform (always) | DevicePlatform (one of ios, android, web) | |
screen | string | The named route on screen, when the app knows it. |
session_id (always) | string | The app’s id for this time in front, drawn when it opened or came back: a guest is shown one large message a session. |
time_zone | string | The phone’s IANA zone, for quiet hours and sending windows; left out when the phone does not say. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | Checkin | 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. |
Open a message by its link
Section titled “Open a message by its link”POST /guest/v1/messages/{message_id}/open
The in-app message a link names, to show over the page, whatever its audience says: the user asked for it.
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 |
|---|---|---|
message_id (required) | path | The in-app message’s id. |
Body (application/json): OpenMessageBody
| Field | Type | Description |
|---|---|---|
session_id (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | InAppMessage | 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. |
Say what the user did with a message
Section titled “Say what the user did with a message”POST /guest/v1/receipts
Seen, tapped, dismissed, a carousel’s screens and buttons, or a goal: one receipt per thing the user did.
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): ReceiptBody
| Field | Type | Description |
|---|---|---|
action (always) | ReceiptAction (one of seen, clicked, dismissed, completed, answered) | |
answers | array of string | |
button | string | |
link | string | What was tapped, for clicked. |
message_id (always) | string | |
path | array of string | |
screen | string | A carousel’s receipts say where the guest was. Screen is the screen it is about: the one answered, the one whose button was tapped, the one the carousel ended or was closed on. Button is the button tapped, for clicked (with Link too, for a link button). Answers are the options picked, for answered: one for a single choice, up to MaxCarouselOptions for a multiple. Path is the screens’ ids the guest has seen so far, in order (a screen seen twice is in it twice), at most MaxReceiptPath (the first ones kept), for completed and dismissed, and on any other carousel receipt that has it. |
session_id | string | The check-in’s session. |
test | boolean | About a test copy (InAppMessage.Test): MessageID is the test’s. |
variant (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 204 | none | Done, with nothing to say |
| 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. |
Answer a survey’s question
Section titled “Answer a survey’s question”POST /guest/v1/surveys/{message_id}/answers
Keeps one answer as it is given, so a survey left half way still counts.
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 |
|---|---|---|
message_id (required) | path | The in-app message’s id. |
Body (application/json): SurveyAnswerBody
| Field | Type | Description |
|---|---|---|
answers (always) | array of SurveyAnswer | |
test | boolean | A test copy’s answers (InAppMessage.Test), by the test’s id. |
variant (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 204 | none | Done, with nothing to say |
| 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. |
Finish a survey
Section titled “Finish a survey”POST /guest/v1/surveys/{message_id}/submit
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 |
|---|---|---|
message_id (required) | path | The in-app message’s id. |
Body (application/json): SurveySubmit
| Field | Type | Description |
|---|---|---|
answers (always) | array of SurveyAnswer | |
test | boolean | A test copy finished (InAppMessage.Test): nothing is written to the guest’s attributes. |
variant (always) | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 204 | none | Done, with nothing to say |
| 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. |