Cloud Chat: Import Ticket History

Important

Importing tickets via API can only be done after the migration is completed and with the inbox already created and active in Cloud Chat.

Technical Requirements

To perform this process, it is necessary for the client to have a developer responsible for executing the API requests and structuring the data correctly according to the documentation.

The Cloud Humans team does not perform API imports for clients, only provides the technical documentation and implementation guidance.

Ticket History Import via API

To import tickets from another helpdesk via API in Cloud Chat, simply send a POST request to https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import with the access key and structured data as defined below.

Request

curl -X POST \ 
    'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import' \
    --header 'content-type: application/json' \
    --header 'api_access_token: API_TOKEN' \
    --data '{ "conversations_data": [ 
      {
        "contact": {
            "email": "[email protected]",
            "name": "John Doe",
            "phone_number": "+1234567890",
            "identifier": "external_helpdesk_id"
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-16T14:22:00Z",
        "messages": [
          {
            "content": "My printer is on fire! The smoke is very colorful and I need immediate help.",
            "message_type": "incoming",
            "created_at": "2024-01-15T10:30:00Z",
            "private": false
          }
        ]
      }
    ] }'

Request Body

The request body must include:

conversations_data: (mandatory) List of objects containing ticket data, with the following attributes:
- created_at and updated_at (mandatory): creation and last update dates, respectively. Must be in ISO 8601 Date Time format.
- contact (mandatory): object containing contact data related to the ticket. Includes fields:
  - identifier (mandatory): unique identifier for the contact in the external helpdesk.
  - email (optional): contact's email. Must be a valid email.
  - name (optional): contact's name.
  - phone_number (optional): contact's phone number. Must be in international format with the "+" symbol and country code; example: +5599988888888
- messages (mandatory): list of objects containing sent message data in the ticket. Includes fields:
  - content (mandatory): message body.
  - message_type (mandatory): indicates message direction. Use "incoming" for inbound messages (sent by the contact) and "outgoing" for outbound messages (sent by the system or agents during handling).
  - created_at (mandatory): message sending date. Must be in ISO 8601 Date Time format.
  - private (mandatory): indicator of internal (private) message. Use "true" for private messages and "false" for public messages.

Example

{
  "conversations_data": [
    {
      "contact": {
        "email": "[email protected]",
        "name": "John Doe",
        "phone_number": "+1234567890",
        "identifier": "user_6782902"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:22:00Z",
      "messages": [
        {
          "content": "My printer is on fire! The smoke is very colorful and I need immediate help.",
          "message_type": "incoming",
          "created_at": "2024-01-15T10:30:00Z",
          "private": false
        },
        {
          "content": "Thanks for contacting us. I can see this is urgent. Let me help you resolve this immediately.",
          "message_type": "outgoing",
          "created_at": "2024-01-15T10:31:00Z",
          "private": false
        },
        {
          "content": "Internal note: Customer has premium support, prioritize this case.",
          "message_type": "activity",
          "created_at": "2024-01-15T11:16:00Z",
          "private": true
        },
        {
          "content": "**Status Update**: Escalated to Level 2 Support",
          "message_type": "activity",
          "created_at": "2024-01-15T12:00:00Z",
          "private": true
        }
      ]
    }
  ]
}

Important Rules

Unique identifier required: The identifier contact must be unique. Note that two contacts with different data but the same identifier are considered the same contact.
Limits per request: Each request to this endpoint supports up to 10,000 tickets and 15 megabytes. If your import exceeds these limits, you will need to partition the data and send multiple requests to import all data.

Parameters

CLOUDCHAT_DOMAIN: You can find your domain by logging into your CloudChat account. It’s the part of the URL shown in your browser:

ACCOUNT_ID: Found in your account settings section:

API_TOKEN: Found in your profile settings (https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings)

INBOX_ID: Identifier of the inbox that will receive the tickets to be imported. It can be found in the URL of the inbox configuration tab: