# Conversations

This endpoint let you manage all the conversations in the account.

TIP

Fingerprint authentication is supported in the following endpoints:

Create a conversation
Retrieve a conversation
List all conversations

# The conversation object

id integer

The system-generated ID of the conversation.
channel string

The conversation channel. At this moment, only email is supported. More channels will be added soon.
customer_email object when channel=email

The customer email used on the conversation.
mailbox_id integer

The system-generated ID of the conversation mailbox.
mailbox object expandable

The mailbox's object.
user_id integer

The system-generated ID of the user assigned to the conversation. If null, the conversation is considered unassigned.
user object expandable

The object of the user assigned to the conversation.
number integer

The number of the conversation.
status string

The status of the conversation. Possible values are posted, draft, pending, and closed.
subject string

The subject of the conversation.
preview string

A preview of the last interaction message.
realtime_channel string

The channel where realtime communication can be sent for the conversation.
customer_awaiting_reply_since string

If customer has replied the conversation, this attribute contains the date of that interaction. When an agent replies, the value of this attribute is null.
tags array

The list of tags attached to the conversation. See conversation tags object reference.
customer object expandable

The object of the customer.
created_at string

The timestamp when the conversation was created.
updated_at string

The timestamp when the conversation was last updated.

# The conversation object

{
  "id": 1,
  "channel": "email",
  "customer_email": {
    "id": 1,
    "email": "jane@example.org"
  },
  "mailbox_id": 1,
  "mailbox": {...},
  "user_id": null,
  "number": 1,
  "status": "posted",
  "subject": "Problem with order",
  "preview": "Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly...",
  "realtime_channel": "account.1.conversation.1",
  "customer_awaiting_reply_since": null,
  "tags": [],
  "updated_at": "2019-06-01T18:47:16+00:00",
  "created_at": "2019-06-01T16:12:25+00:00",
  "customer": {
    "id": 1,
    "name": "Jane Doe",
    "initials": "JD",
    "first_name": "Jane",
    "last_name": "Doe",
    "account_id": 1,
    "avatar": null,
    "emails": [
      {
        "id": 1,
        "email": "jane@example.org"
      }
    ],
    "phones": [],
    "websites": [],
    "updated_at": "2019-06-01T16:12:25+00:00",
    "created_at": "2019-06-01T16:12:25+00:00"
  },
  "user": null,
  "unread_count": 1
}

# Create a conversation

mailbox_id integer optional, account default mailbox is used

The mailbox id where the conversation will be placed.
user_id integer optional, default=null (unassigned)

The user id assigned to the conversation.
status string optional, default=posted

The status of the conversation. Possible values are posted, draft, pending, and closed.
subject string optional

The subject of the conversation.
channel string required

The channel of the conversation. For now, only email channel is supported.
to string required if channel=email

The customer email where the interactions will be sent to.
interactions array of interactions optional

The interactions of the conversation.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d mailbox_id=1 \
  -d user_id=1 \
  -d status="pending" \
  -d subject="Need help with my order" \
  -d channel="email" \
  -d to="jane@example.org" \
  -d interactions[0][type]="customer" \
  -d interactinos[0][body]="Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly..."

# Sample successful response

{
  "data": {
    "id": 1,
    "channel": "email",
    "customer_email": {
      "id": 1,
      "email": "jane@example.org"
    },
    "mailbox_id": 1,
    "mailbox": {...},
    "user_id": null,
    "number": 1,
    "status": "posted",
    "subject": "Need help with my order",
    "preview": "Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly...",
    "realtime_channel": "account.1.conversation.1",
    "customer_awaiting_reply_since": null,
    "tags": [],
    "updated_at": "2019-06-01T18:47:16+00:00",
    "created_at": "2019-06-01T16:12:25+00:00",
    "customer": {
      "id": 1,
      "name": "Jane Doe",
      "initials": "JD",
      "first_name": "Jane",
      "last_name": "Doe",
      "account_id": 1,
      "avatar": null,
      "emails": [
        {
          "id": 1,
          "email": "jane@example.org"
        }
      ],
      "phones": [],
      "websites": [],
      "updated_at": "2019-06-01T16:12:25+00:00",
      "created_at": "2019-06-01T16:12:25+00:00"
    },
    "user": null,
    "unread_count": 1
  }
}

# Retrieve a conversation

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": {
    "id": 1,
    "channel": "email",
    "customer_email": {
      "id": 1,
      "email": "jane@example.org"
    },
    "mailbox_id": 1,
    "mailbox": {...},
    "user_id": null,
    "number": 1,
    "status": "posted",
    "subject": "Need help with my order",
    "preview": "Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly...",
    "realtime_channel": "account.1.conversation.1",
    "customer_awaiting_reply_since": null,
    "tags": [],
    "updated_at": "2019-06-01T18:47:16+00:00",
    "created_at": "2019-06-01T16:12:25+00:00",
    "customer": {
      "id": 1,
      "name": "Jane Doe",
      "initials": "JD",
      "first_name": "Jane",
      "last_name": "Doe",
      "account_id": 1,
      "avatar": null,
      "emails": [
        {
          "id": 1,
          "email": "jane@example.org"
        }
      ],
      "phones": [],
      "websites": [],
      "updated_at": "2019-06-01T16:12:25+00:00",
      "created_at": "2019-06-01T16:12:25+00:00"
    },
    "user": null,
    "unread_count": 1
  }
}

# Update a conversation

mailbox_id integer optional, account default mailbox is used

The mailbox id where the conversation will be placed.
user_id integer optional, default=null (unassigned)

The user id assigned to the conversation.
status string optional, default=posted

The status of the conversation. Possible values are posted, draft, pending, and closed.
subject string required

The subject of the conversation.

# Sample request

The following request assigns the conversation to the user with ID 1 and sets the conversation in pending status:

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d user_id=1 \
  -d status="pending" \
  -d subject="Need help with my order"

# Sample successful response

{
  "data": {
    "id": 1,
    "channel": "email",
    "customer_email": {
      "id": 1,
      "email": "jane@example.org"
    },
    "mailbox_id": 1,
    "mailbox": {...},
    "user_id": 1,
    "number": 1,
    "status": "pending",
    "subject": "Need help with my order",
    "preview": "Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly...",
    "realtime_channel": "account.1.conversation.1",
    "customer_awaiting_reply_since": null,
    "tags": [],
    "updated_at": "2019-06-01T18:47:16+00:00",
    "created_at": "2019-06-01T16:12:25+00:00",
    "customer": {
      "id": 1,
      "name": "Jane Doe",
      "initials": "JD",
      "first_name": "Jane",
      "last_name": "Doe",
      "account_id": 1,
      "avatar": null,
      "emails": [
        {
          "id": 1,
          "email": "jane@example.org"
        }
      ],
      "phones": [],
      "websites": [],
      "updated_at": "2019-06-01T16:12:25+00:00",
      "created_at": "2019-06-01T16:12:25+00:00"
    },
    "user": {
      "id": 1,
      "name": "José Báez",
      "initials": "JB",
      "is_me": true,
      "avatar": null
    },
    "unread_count": 1
  }
}

# Delete a conversation

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1 \
  --request DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

# Delete multiple conversations

conversations array

An array of conversations ids to delete. Limited to 100 ids.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/bulk \
  --request DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d conversations[0]=1 \
  -d conversations[0]=2

If successful, the above request will return an empty response with 204 HTTP status code.

# List all conversations

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations \
  -G \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

# Sample successful response

{
  "data": [
    {
      "id": 1,
      "channel": "email",
      "customer_email": {
        "id": 1,
        "email": "jane@example.org"
      },
      "mailbox_id": 1,
      "mailbox": {...},
      "user_id": 1,
      "number": 1,
      "status": "pending",
      "subject": "Need help with my order",
      "preview": "Hello. I'm having problem placing an order. The checkout doesn't seems to be working properly...",
      "realtime_channel": "account.1.conversation.1",
      "customer_awaiting_reply_since": null,
      "tags": [],
      "updated_at": "2019-06-01T18:47:16+00:00",
      "created_at": "2019-06-01T16:12:25+00:00",
      "customer": {
        "id": 1,
        "name": "Jane Doe",
        "initials": "JD",
        "first_name": "Jane",
        "last_name": "Doe",
        "account_id": 1,
        "avatar": null,
        "emails": [
          {
            "id": 1,
            "email": "jane@example.org"
          }
        ],
        "phones": [],
        "websites": [],
        "updated_at": "2019-06-01T16:12:25+00:00",
        "created_at": "2019-06-01T16:12:25+00:00"
      },
      "user": {
        "id": 1,
        "name": "José Báez",
        "initials": "JB",
        "is_me": true,
        "avatar": null
      },
      "unread_count": 1
    },
    {...}
  ]
}

# Retrieve context

This endpoint lets you retrieve a context that tells you or your customers whether your help desk is online and which agents are available based on their availability preferences.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/context \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": {
    "active_users": [
      {
        "id": 1,
        "user_id": 1,
        "account_id": 1,
        "user": {
          "id": 1,
          "name": "Jane Doe",
          "initials": "JD",
          "avatar": null
        },
        "is_online": true,
        "last_activity": "2019-11-11T04:00:16+00:00"
      }
    ],
    "is_online": true
  }
}

← Customer PGP Public Keys Conversation interactions →

# Conversations

# The conversation object

id integer

channel string

customer_email object when channel=email

mailbox_id integer

mailbox object expandable

user_id integer

user object expandable

number integer

status string

subject string

preview string

realtime_channel string

customer_awaiting_reply_since string

tags array

customer object expandable

created_at string

updated_at string

# The conversation object

# Create a conversation

mailbox_id integer optional, account default mailbox is used

user_id integer optional, default=null (unassigned)

status string optional, default=posted

subject string optional

channel string required

to string required if channel=email

interactions array of interactions optional

# Sample request

# Sample successful response

# Retrieve a conversation

# Sample request

# Sample successful response

# Update a conversation

mailbox_id integer optional, account default mailbox is used

user_id integer optional, default=null (unassigned)

status string optional, default=posted

subject string required

# Sample request

# Sample successful response

# Delete a conversation

# Delete multiple conversations

conversations array

# Sample request

# List all conversations

# Sample request

# Sample successful response

# Retrieve context

# Sample request

# Sample successful response