Principal APIs Cloud Chat: Import de histórico de tickets

Cloud Chat: Import de histórico de tickets

Última atualização em Feb 11, 2026

Importante

A importação de tickets via API só pode ser realizada após a conclusão da migração e com a inbox já criada e ativa no Cloud Chat.

Requisito técnico

Para realizar esse processo, é necessário que o cliente possua um desenvolvedor responsável por executar as requisições na API e estruturar os dados corretamente conforme a documentação.

O time da Cloud Humans não realiza a importação via API para o cliente, apenas disponibiliza a documentação técnica e orientações para implementação.

Import de histórico de tickets via API

Para importar tickets advindos de outro helpdesk via API no Cloud Chat, basta enviar uma POST request para https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import enviando a chave de acesso e os dados estruturados da maneira definida abaixo.

Requisição

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

Corpo da requisição

O corpo da requisição deve conter:

  • conversations_data: (obrigatório) Lista de objetos com os dados dos tickets, com os seguintes atributos:

    • created_at e updated_at (obrigatórios): datas de criação e de última atualização, respectivamente. Devem estar no padrão de Date Time ISO 8061.

    • contact (obrigatório): objeto contendo os dados do contato relacionado ao ticket. Contém os campos:

      • identifier (obrigatório): identificador único do contato no helpdesk externo.

      • email (opcional): email do contato. Deve ser um email válido.

      • name (opcional): nome do contato.

      • phone_number (opcional): telefone do contato. Deve estar no padrão internacional com o caractere "+" e o código do país; exemplo: +5599988888888

    • messages (obrigatório): lista de objetos contendo os dados das mensagens enviadas no ticket. Possui os seguintes campos:

      • content (obrigatório): corpo da mensagem.

      • message_type (obrigatório): indicador de direção da mensagem. Utilize o valor "incoming" para designar mensagens inbound (enviadas pelo contato) e "outgoing" para mensagens outbound (enviadas pelo sistema ou por agentes durante o atendimento).

      • created_at (obrigatório): data de envio da mensagem. Deve estar no padrão de Date Time ISO 8061.

      • private (obrigatório): indicador de mensagem interna (privada). Utilize o valor "true" para mensagens privadas e "false" para mensagens públicas.

Exemplo

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

Regras importantes

  • Identificador único obrigatório: O identificador do contato identifier deve ser único. Note que dois contatos com dados divergentes porém mesmo identificador serão considerados como um mesmo contato.

  • Limites por requisição: Cada requisição para esse endpoint possui os seguintes limites: 10.000 tickets e 15 megabytes. Caso seu import ultrapasse esse limite, será necessário particionar os dados e efetuar a quantidade correspondente de requisições para a importação de todos os dados.

Parâmetros

CLOUDCHAT_DOMAIN: Você pode obter seu domínio ao fazer login na sua conta no CloudChat. É a parte que aparece na URL do navegador:

ACCOUNT_ID: Obtido na seção de configurações da conta:

API_TOKEN: Obtido nas configurações do perfil (https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings)

INBOX_ID: Identificador da caixa que receberá os tickets a serem importados. Pode ser obtido na URL da aba de configurações da inbox: