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

Field	Type	Description
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

Field	GET	POST	PATCH
channel	X	X
identifier	X	X	X
chatbotPaused	X	x	x
createdAt	X
updatedAt	x

Required Fields for Creation (POST)

Field	Type	Example value
channel	String	whatsapp
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=messages

Response

{
  "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

Create a MessageThread

post

Authorizations

Body

Responses

201

MessageThread created

422

combination of identifier and channel should be unique

post

HTTPcURLJavaScriptPython

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

Retrieve a single message_thread

get

Authorizations

Path parameters

idstringRequired

Responses

200

message_thread found

application/vnd.api+json

401

access denied

404

MessageThread not found

get

HTTPcURLJavaScriptPython

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": {}
}

Retrieve all MessageThreads

get

Authorizations

Responses

200

message_threads found

application/vnd.api+json

401

access denied

get

HTTPcURLJavaScriptPython

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
  }
}

Update a MessageThread

patch

Authorizations

Path parameters

idstringRequired

Body

Responses

200

Change of CandidateId is allowed when candidate_id is nil

application/vnd.api+json

401

access denied

404

MessageThread not found

422

Phone number must have a country code when channel is whatsapp

patch

HTTPcURLJavaScriptPython

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": {}
}