This endpoint allows tracking conversations, interlocutors and messages in a single API call. It's the easiest way to instrument a conversational application without having to manage state.

curl -X POST -H "Content-Type: application/json" -d '{
  "message": {
    "platform": "messenger",
    "provider": "dialog-node",
    "mtype": "text",
    "sent_at": ,
    "nlp": {
      "intents": [{
        "name": "rocket.launch",
        "confidence": 0.98
    "properties": {
      "text": "Launch some space rockets"
  "conversation": {
    "distinct_id": ""
  "creator": {
    "distinct_id": "",
    "type": "interlocutor",
    "username": "elon",
    "phone": "141812312345",
    "email": "",
    "first_name": "Elon",
    "last_name": "Musk",
    "gender": "male",
    "locale": "us",
    "profile_picture": "",
    "timezone": -7
}' ''

You must provide the /track endpoint with three core resources: message, conversation, and creator.

Param Description
platform string Required

The platform on which the message is sent. See all accepted values.

mtype string Required

Message type. Refer to message types for supported values.

Note that additional properties are expected depending on the message type.

sent_at number Required

A Unix timestamp with milliseconds.

Note that precision is important and preferable in all cases since a system could generate multiple messages during the same second.

Example: 1474215799.4329312, 1474215799.432 or 1474215799 are valid values.

provider string Optional

The provider via which the message is sent. This is a user-defined attribute that can be used to segment and enforce some of your business logic.

Example: smooch, botpress-dialog.

name string Optional

A message name allows to group similar messages together. Messages should have the same name if a bot sends many of them and personalizes a small part of it.

Example: welcome, humor, content.

nlp hash Optional

Natural Language Processing (NLP) or Natural Language Understanging (NLU) message metadata.

intents array

Collection of intents detected in the message.

Property Description
name string Required

Name of the intent. Maximum length of 256 characters.

confidence float Optional

Confidence of the intent's classification in percent.

properties hash Optional

Additional message properties. Used to add required metadata dependent on message types.

Param Description
distinct_id string Required

A unique conversation ID issued by the messaging platform. ID must be unique amongst the bot's conversation IDs.

If the distinct_id is seen for the first time, then a new conversation will be created.

Param Description
distinct_id string Required

ID of the sender, either a unique user ID or the bot's ID. If the type is interlocutor then ID must be unique amongst the bot's interlocutor IDs.

If the distinct_id is from a user and is seen for the first time, then a new interlocutor will be created.

type string Required

Either interlocutor or bot. Case insensitive.

username, phone, email, first_name, last_name, gender, locale, profile_picture, timezone Optional

If the type is interlocutor, then additional interlocutor properties can also be set.