Cloud Chat: Import de histórico de tickets

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: