MessageThread
MessageThread houses all information to facilitate communication with a candidate. It contains the communication channel e.g WhatsApp, SMS, Facebook Messenger, etc. It also contains the identifier for said channel e.g the phone number for WhatsApp, the Facebook profile id for Facebook Messenger, etc. as well as the messages that have been sent and received.
Candidate
Optionally, a candidate can be associated with a message thread. This is required when embedding the Recrubo Inbox. The association between a MessageThread and a Candidate can not be changed once set. Channels and identifiers can be updated.
Endpoints
GET /message-threads- Retrieves a list of all message threads.GET /message-threads/{id}- Retrieves a specific message thread by ID.POST /message-threads- Creates a new message thread.PATCH /message-threads/{id}- Updates a specific message thread by ID.DELETE /message-threads/{id}- Deletes a specific message thread by ID.
Attributes
channel
String
The channel used for communication with the candidate.
identifier
String
The identifier for the channel used for communication with the candidate.
chatbotPaused
Boolean
The check for our services to reply to a message with the currently enabled flow. This can be used to stop flows from starting or continuing.
createdAt
DateTime
The timestamp when the message thread was created.
updatedAt
DateTime
The timestamp when the message thread was last updated.
HTTP Methods
channel
X
X
identifier
X
X
X
chatbotPaused
X
x
x
createdAt
X
updatedAt
x
Required Fields for Creation (POST)
channel
String
identifier
String
31612345678
chatbotPaused
Boolean
true
Example POST body
{
"data": {
"type": "messageThreads",
"attributes": {
"channel": "whatsapp",
"identifier": "31612345678"
}
}
}Example PATCH body with candidate
{
"data": {
"type": "messageThreads",
"attributes": {
"identifier": "3187654321",
"chatbotPaused": true
},
"relationships": {
"candidate": {
"data": {
"type": "candidates",
"id": "2e23b4b4-4b4b-4b4b-4b4b-4b4b4b4b4b4b"
}
}
}
}
}
or directly with the candidate id:
{
"data": {
"type": "messageThreads",
"attributes": {
"channel": "whatsapp",
"identifier": "3187654321",
"candidateId": "2e23b4b4-4b4b-4b4b-4b4b-4b4b4b4b4b4b"
}
}
}Including Messages
To include messages in the response, add the include=messages query parameter.
GET /message-threads?include=messagesResponse
{
"data": [
{
"type": "messageThreads",
"id": "7135853f-26ac-4a65-9044-cab092806249",
"attributes": {
"channel": "whatsapp",
"identifier": "31612345678"
},
"relationships": {
"messages": {
"data": [
{
"type": "messages",
"id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9"
}
]
}
}
}
],
"included": [
{
"type": "messages",
"id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
"attributes": {
"direction": "outgoing",
"content": "Hello, how are you?",
"status": "sent"
}
}
]
}OpenAPI
MessageThread created
No content
combination of identifier and channel should be unique
POST /public/v2/message-threads HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 152
{
"data": {
"id": "text",
"type": "text",
"attributes": {
"channel": "whatsapp",
"identifier": "31612345678",
"candidateId": "123e4567-e89b-12d3-a456-426614174000"
}
}
}No content
message_thread found
access denied
MessageThread not found
GET /public/v2/message-threads/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*
{
"data": {
"id": "77e76b4d-71a8-46a9-8348-d833d02cbba2",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:09+00:00",
"updatedAt": "2024-08-20T10:45:09+00:00",
"channel": "whatsapp",
"identifier": "31694395128",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=77e76b4d-71a8-46a9-8348-d833d02cbba2"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=77e76b4d-71a8-46a9-8348-d833d02cbba2"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=77e76b4d-71a8-46a9-8348-d833d02cbba2"
}
}
}
},
"meta": {}
}message_threads found
access denied
GET /public/v2/message-threads HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "80da620e-a322-4a55-a83b-9346751aac3c",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:08+00:00",
"updatedAt": "2024-08-20T10:45:08+00:00",
"channel": "whatsapp",
"identifier": "31689786047",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=80da620e-a322-4a55-a83b-9346751aac3c"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=80da620e-a322-4a55-a83b-9346751aac3c"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=80da620e-a322-4a55-a83b-9346751aac3c"
}
}
}
},
{
"id": "b7fd4377-6e8a-4f04-a4b6-73bf5ac5a273",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:08+00:00",
"updatedAt": "2024-08-20T10:45:08+00:00",
"channel": "whatsapp",
"identifier": "31628971684",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=b7fd4377-6e8a-4f04-a4b6-73bf5ac5a273"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=b7fd4377-6e8a-4f04-a4b6-73bf5ac5a273"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=b7fd4377-6e8a-4f04-a4b6-73bf5ac5a273"
}
}
}
},
{
"id": "efa3232a-68b5-4cc9-8132-e2e875ab89e7",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:08+00:00",
"updatedAt": "2024-08-20T10:45:08+00:00",
"channel": "whatsapp",
"identifier": "31651229555",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=efa3232a-68b5-4cc9-8132-e2e875ab89e7"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=efa3232a-68b5-4cc9-8132-e2e875ab89e7"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=efa3232a-68b5-4cc9-8132-e2e875ab89e7"
}
}
}
},
{
"id": "94ddbbc9-eb8d-4efa-a099-deb0444d21ba",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:08+00:00",
"updatedAt": "2024-08-20T10:45:08+00:00",
"channel": "whatsapp",
"identifier": "31681969205",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=94ddbbc9-eb8d-4efa-a099-deb0444d21ba"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=94ddbbc9-eb8d-4efa-a099-deb0444d21ba"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=94ddbbc9-eb8d-4efa-a099-deb0444d21ba"
}
}
}
}
],
"meta": {
"total": 4,
"totalUnfiltered": 4,
"currentSize": 25,
"currentPage": 1,
"maxPage": 1
}
}Change of CandidateId is allowed when candidate_id is nil
access denied
MessageThread not found
Phone number must have a country code when channel is whatsapp
PATCH /public/v2/message-threads/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 152
{
"data": {
"id": "text",
"type": "text",
"attributes": {
"channel": "whatsapp",
"identifier": "31612345678",
"candidateId": "123e4567-e89b-12d3-a456-426614174000"
}
}
}{
"data": {
"id": "c6ab8344-576f-4ce0-b7d6-e706ebb921d2",
"type": "messageThreads",
"attributes": {
"createdAt": "2024-08-20T10:45:09+00:00",
"updatedAt": "2024-08-20T10:45:09+00:00",
"channel": "whatsapp",
"identifier": "31611111110",
"candidateId": null
},
"relationships": {
"candidate": {
"links": {
"related": null
}
},
"flowRuns": {
"links": {
"related": "/public/v2/flow-runs?filter[messageThreadId]=c6ab8344-576f-4ce0-b7d6-e706ebb921d2"
}
},
"messages": {
"links": {
"related": "/public/v2/messages?filter[messageThreadId]=c6ab8344-576f-4ce0-b7d6-e706ebb921d2"
}
},
"conversation": {
"links": {
"related": "/public/v2/conversations?filter[messageThreadId]=c6ab8344-576f-4ce0-b7d6-e706ebb921d2"
}
}
}
},
"meta": {}
}Last updated