Principal APIs Como importar histórico de tickets via API

Como importar histórico de tickets via API

Última atualização em May 21, 2026

Quando usar

  • Você concluiu a migração de outro helpdesk para o Cloud Chat e quer importar o histórico de tickets
  • Você precisa preservar metadados (ID externo, prioridade, fila de origem) para auditoria ou referência cruzada
  • Você está montando uma rotina de importação programática para grandes volumes

Pré-requisitos

  • Migração concluída e inbox criada e ativa no Cloud Chat

  • API Key em mãos — ver Como encontrar sua API Key no Cloud Chat

  • CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID

  • Desenvolvedor disponível para executar as requisições e estruturar os dados

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

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

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import

Headers

Header Valor
content-type application/json
api_access_token Seu token de API

Exemplo de 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_customer_id"
        },
        "custom_attributes": {
          "external_helpdesk_id": "ZD-12345",
          "priority": "high"
        },
        "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

Estrutura do conversations_data

Lista de objetos com os dados dos tickets. Cada objeto tem:

Campo Obrigatório Descrição
created_at Sim Data de criação do ticket. Formato ISO 8601
updated_at Sim Data da última atualização. Formato ISO 8601
contact Sim Objeto com dados do contato (ver abaixo)
custom_attributes Não Pares chave-valor para metadata (ID externo, prioridade, fila)
messages Sim Lista de mensagens do ticket

Objeto contact

Campo Obrigatório Descrição
identifier Sim Identificador único do contato no helpdesk de origem
email Não E-mail válido
name Não Nome do contato
phone_number Não Telefone em E.164 (ex: +5599988888888)

custom_attributes (recomendado)

Pares chave-valor para preservar metadados do ticket de origem (ex: external_helpdesk_id, prioridade, fila). Aceita qualquer chave string. Os valores ficam disponíveis na conversa via API (GET /conversations/:id) e na UI no painel direito.

Dica: para que o atributo apareça com label/tipo formatado no painel, defina-o previamente em Settings → Custom Attributes (escopo: Conversation). Sem isso, o valor é gravado no banco e fica acessível via API, mas não é renderizado como campo nativo na UI.

Objetos messages

Campo Obrigatório Descrição
content Sim Corpo da mensagem
message_type Sim "incoming" (mensagem do contato) ou "outgoing" (mensagem do agente). Para notas internas, use "activity" com "private": true
created_at Sim Data de envio. Formato ISO 8601
private Sim true para mensagem privada (interna), false para pública

Exemplo completo com múltiplas mensagens

{
  "conversations_data": [
    {
      "contact": {
        "email": "[email protected]",
        "name": "John Doe",
        "phone_number": "+1234567890",
        "identifier": "user_6782902"
      },
      "custom_attributes": {
        "external_helpdesk_id": "ZD-78901",
        "priority": "high",
        "source_queue": "tier-2-support"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:22:00Z",
      "messages": [
        {
          "content": "My printer is on fire!",
          "message_type": "incoming",
          "created_at": "2024-01-15T10:30:00Z",
          "private": false
        },
        {
          "content": "Thanks for contacting us. Let me help.",
          "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 — identifier do contato deve ser único. Dois contatos com dados divergentes mas mesmo identificador serão tratados como um único contato

  • Limites por requisição — cada requisição aceita no máximo 10.000 tickets ou 15 MB. Para volumes maiores, particione e faça múltiplas requisições

Onde encontrar os parâmetros

CLOUDCHAT_DOMAIN

Parte da URL ao fazer login na sua conta:

ACCOUNT_ID

Em Configurações da conta:

API_TOKEN

Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings:

INBOX_ID

ID da caixa que receberá os tickets. Pode ser obtido na URL da aba de configurações da inbox:

Observações