Developers

# Conversation interactions

Conversation interactions are all the interactions within a single conversation. For example, a customer reply is an interaction of type customer and an agent reply is an interaction of type user. The agent can also create conversation-level notes, which is an interaction of type note.

Note & tip

  1. Other types of interactions could be added in the future, keep this in mind when developing around this API.
  2. Fingerprint authentication is supported in this endpoint.

# The user interaction object

  • id integer

    The system-generated ID of the interaction.

  • type string type=user

    The type of interaction, in this case value is user.

  • status string

    The status of the interaction. Possible values are posted (default), draft.

  • body string

    The message body of the interaction.

  • to array

    List of recipients email addresses. Please note that this attribute was added in v0.9. Interactions of old conversations will not have any recipient listed in this field, however, you can safely retrieve the recipient from the customer_email attribute in a conversation object.

  • cc array

    List of carbon-copied email addresses.

  • bcc array

    List of black carbon-copied email addresses.

  • user object expandable

    The user that created the interaction.

  • posted_by object expandable

    The user who posted/sent the interaction. In most cases, both user and posted_by are the same object. When the interaction is in draft status, this value is null. If the interaction is posted and this attribute is null, the person on the user attribute is considered the poster/sender.

  • attachments array of objects expandable

    The list of attachments of the interaction.

  • conversation_id integer

    The conversation id where the interaction belongs to.

  • is_starter boolean

    Whether the interaction is the interaction that started the conversation. Only user or customer interactions can be considered as starters.

  • is_forward boolean

    Whether the interaction is a forward.

  • seen_at string

    The timestamp when the interaction was seen by the customer.

  • created_at string

    The timestamp when the interaction was created.

  • updated_at string

    The timestamp when the interaction was last updated.

# The user interaction object

{
  "id": 1,
  "type": "user",
  "status": "posted",
  "body": "Hello. The checkout issue has been resolved, thank you!",
  "to": [],
  "cc": [],
  "bcc": [],
  "user": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "posted_by": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "attachments": [],
  "is_starter": false,
  "is_forward": false,
  "seen_at": null,
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# The customer interaction object

  • id integer

    The system-generated ID of the interaction.

  • type string type=customer

    The type of interaction, in this case value is customer.

  • body string

    The message body of the interaction.

  • source string

    The source of the interaction. For example, when a customer sends a message using the chat, chat is the source.

  • attachments array of objects expandable

    The list of attachments of the interaction.

  • customer object expandable

    The customer who sent the interaction.

  • customer_email object

    The customer email used to sent the interaction via email.

  • conversation_id integer

    The conversation id where the interaction belongs to.

  • is_starter boolean

    Whether the interaction is the interaction that started the conversation. Only user or customer interactions can be considered as starters.

  • created_at string

    The timestamp when the interaction was created.

  • updated_at string

    The timestamp when the interaction was last updated.

# The customer interaction object

{
  "id": 1,
  "type": "customer",
  "body": "Hello. I'm having problems placing an order.",
  "source": "chat",
  "attachments": [],
  "customer": {...},
  "customer_email": {
    "id": 1,
    "email": "jane@example.org"
  },
  "is_starter": true,
  "is_forward": false,
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# The note interaction object

  • id integer

    The system-generated ID of the interaction.

  • type string type=note

    The type of interaction, in this case value is note.

  • body string

    The message body of the interaction.

  • user object expandable

    The user that created the note.

  • attachments array of objects expandable

    The list of attachments of the interaction.

  • conversation_id integer

    The conversation id where the interaction belongs to.

  • created_at string

    The timestamp when the interaction was created.

  • updated_at string

    The timestamp when the interaction was last updated.

# The note interaction object

{
  "id": 1,
  "type": "note",
  "body": "Hello. I'm having problems placing an order.",
  "user": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "attachments": [],
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# Create an interaction

# User interaction attributes

  • type string required

    The type of interaction, in this case value should be user.

  • status string optional, default=posted

    The status of the interaction. Possible values are posted and draft.

  • body string required if status=posted

    The message body of the interaction.

  • to array of email addresses optional

    List of recipients email addresses. The interaction email will be sent to the customer email address attached to the conversation if this field is empty.

  • cc array of email addresses optional

    List of carbon-copied email addresses.

  • bcc array of email addresses optional

    List of black carbon-copied email addresses.

  • is_forward boolean

    Whether the interaction is a forward. Forwarded interactions are not visible to the customer.

# Customer interaction attributes

  • type string required

    The type of interaction, in this case value should be customer.

  • body string required

    The message body of the interaction.

  • source string optional

    The source of the interaction.

# Note interaction attributes

  • type string required

    The type of interaction, in this case value should be note.

  • body string optional

    The message body of the interaction.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1/interactions \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d type="user" \
  -d body="Hello. The checkout issue has been resolved!" \
  -d status="draft"

# Sample successful response

{
  "id": 1,
  "type": "user",
  "status": "draft",
  "body": "Hello. The checkout issue has been resolved!",
  "cc": [],
  "bcc": [],
  "user": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "posted_by": null,
  "attachments": [],
  "is_starter": false,
  "is_forward": false,
  "seen_at": null,
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# Retrieve an interaction

# Sample request

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

# Sample successful response

{
  "id": 1,
  "type": "user",
  "status": "draft",
  "body": "Hello. The checkout issue has been resolved!",
  "cc": [],
  "bcc": [],
  "user": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "attachments": [],
  "is_starter": false,
  "is_forward": false,
  "seen_at": null,
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# Update an interaction

# User interaction attributes

  • status string optional, default=posted

    The status of the interaction. Possible values are posted and draft.

  • body string required if status=posted

    The message body of the interaction.

  • to array of email addresses optional

    List of recipients email addresses. The interaction email will be sent to the customer email address attached to the conversation if this field is empty.

  • cc array of email addresses optional

    List of carbon-copied email addresses.

  • bcc array of email addresses optional

    List of black carbon-copied email addresses.

  • is_forward boolean

    Whether the interaction is a forward. Forwarded interactions are not visible to the customer.

# Customer interaction attributes

  • body string required

    The message body of the interaction.

  • source string optional

    The source of the interaction.

# Note interaction attributes

  • body string optional

    The message body of the interaction.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1/interactions/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d body="Hello. The checkout issue has been resolved, thank you!" \
  -d status="posted"

# Sample successful response

{
  "id": 1,
  "type": "user",
  "status": "posted",
  "body": "Hello. The checkout issue has been resolved, thank you!",
  "cc": [],
  "bcc": [],
  "user": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "posted_by": {
    "id": 1,
    "name": "John Doe",
    "initials": "JD",
    "is_me": true,
    "avatar": null
  },
  "attachments": [],
  "is_starter": false,
  "is_forward": false,
  "seen_at": null,
  "updated_at": "2019-04-23T21:37:42+00:00",
  "created_at": "2019-04-23T21:37:42+00:00",
  "conversation_id": 1,
}

# Delete an interaction

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/conversations/1/interactions/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.

← Conversation attachments →