Descrição

🚧
Esteja ciente de que você não poderá executar esta etapa descrita acima diretamente na seção de Referência da API devido a limitações da ferramenta: não é possível calcular os cabeçalhos necessários e enviar uma solicitação simultaneamente.

Este método permite enviar mensagens de entrada e saída ou importar mensagens enviadas em um aplicativo de terceiros.

O método gerará uma mensagem e, se necessário, o próprio chat para o msgid e conversation_id especificados.

Tipo de mensagem	Caso de uso	Parâmetros que devem ser passados
Entrada do: client	Um cliente envia uma mensagem para o canal conectado.	Apenas o campo `payload[sender]` está preenchido, o campo `payload[receiver]` não é enviado.
Saída do: usuário da Kommo para: o cliente	Um gerente escreve uma mensagem para o cliente, e podemos identificar quem enviou a mensagem.	Os campos `payload[sender]` (informações sobre o gerente) e `payload[receiver]` (informações sobre o cliente) estão preenchidos. Um ID de usuário do Kommo é passado para `payload[sender][ref_id]` (você pode obter essa informação através de uma solicitação GET para a lista de usuários, usando o parâmetro de consulta `?with=amojo_id`).
Saída do: bot de integração para: o cliente	Um gerente escreve uma mensagem para o cliente, e não podemos identificar quem enviou a mensagem.	Os campos `payload[sender]` (informações sobre o bot) e `payload[receiver]` (informações sobre o cliente) estão preenchidos. O ID do bot de integração, que foi recebido ao registrar o canal na API de chat, é passado para o campo `payload[sender][ref_id]`.

Usando este método da API, você pode importar em massa mensagens antigas para um chat.

Recomendamos realizar a importação sem notificações para os gerentes ou criar um lead de entrada para todas as mensagens, exceto a última (a mais recente).

Para isso, você deve passar o parâmetro de corpo payload[silent] com valor true para todas as mensagens, exceto para a última, que deve ter o valor false no payload[silent]. Dessa forma, um lead de entrada será criado para a última mensagem, e apenas uma notificação será enviada. Assim, evitaremos perturbações desnecessárias para o usuário.

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639604761,
    "msec_timestamp": 1639604761694,
    "msgid": "my_int-5f2836a8ca475",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "profile": {
        "phone": "+1400000000",
        "email": "example.client@example.com"
      },
      "profile_link": "https://example.com/profile/example.client",
      "name": "Nome do cliente"
    },
    "message": {
      "type": "text",
      "text": "Mensagem de um cliente"
    },
    "silent": false
  }
}

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639604903,
    "msec_timestamp": 1639604903161,
    "msgid": "my_int-5f2836a8ca476",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-manager1_user_id",
      "name": "Nome de usuário",
      "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
    },
    "receiver": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "name": "Nome do cliente",
      "profile": {
        "phone": "+1400000000",
        "email": "example.client@example.com"
      },
      "profile_link": "https://example.com/profile/example.client"
    },
    "message": {
      "type": "text",
      "text": "Mensagem de um usuário"
    },
    "silent": true
  }
}

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639605194,
    "msec_timestamp": 1639605194102,
    "msgid": "my_int-5f2836a8ca477",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-bot_user_id",
      "name": "Bot",
      "ref_id": "f1910c7f-b1e0-4184-bd09-c7def2a9109a"
    },
    "receiver": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "name": "Nome do cliente",
      "profile": {
        "phone": "+1400000000",
        "email": "example.client@example.com"
      },
      "profile_link": "https://example.com/profile/example.client"
    },
    "message": {
      "type": "text",
      "text": "Mensagem do bot"
    },
    "silent": true
  }
}

Ao importar mensagens do bot de integração, os webhooks não são enviados.

Enviando um comentário

O método também permite transferir comentários recebidos e enviados (respostas a comentários enviados em um aplicativo de terceiros).

A principal diferença entre enviar comentários e enviar mensagens é a adição de um campo de postagem à solicitação, que contém o ID da postagem no lado da integração.

{
    "event_type": "new_message",
    "payload": {
        "timestamp": 1639604761,
        "msec_timestamp": 1639604761694,
        "msgid": "my_int-5f2836a8ca475",
        "conversation_id": "my_int-d5a421f7f217",
        "sender": {
            "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
            "avatar": "https://example.com/users/avatar.png",
            "profile": {
                "phone": "+1234567890",
                "email": "example.client@example.com"
            },
            "profile_link": "https://example.com/profile/example.client",
            "name": "Nome do cliente"
        },
        "message": {
            "type": "text",
            "text": "Mensagem do cliente",
            "post": {
                "id": "my-int-376265",
                "url": "https://www.example.com/@example/video/7490",
                "preview_url": "https://example/1/preview.png",
                "preview_permalink": "https://example/2/preview.png",
                "username": "criador da publicação",
                "caption": "Descrição da publicação"
            }
        },
        "silent": false
    }
}

{
    "event_type": "new_message",
    "payload": {
        "timestamp": 1639604903,
        "msec_timestamp": 1639604903161,
        "msgid": "my_int-5f2836a8ca476",
        "conversation_id": "my_int-d5a421f7f217",
        "sender": {
            "id": "my_int-manager1_user_id",
            "name": "Manager name",
            "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
        },
        "receiver": {
            "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
            "avatar": "https://example.com/users/avatar.png",
            "name": "Client name",
            "profile": {
                "phone": "+1234567890",
                "email": "example.client@example.com"
            },
            "profile_link": "https://example.com/profile/example.client"
        },
        "message": {
            "type": "text",
            "text": "Comment from a manager 76fc2bea-902f-425c-9a3d-dcdac4766090",
            "post": {
                "id": "my-int-376265",
                "url": "https://www.example.com/@example/video/7490",
                "preview_url": "https://example/1/preview.png",
                "preview_permalink": "https://example/2/preview.png",
                "username": "post creator",
                "caption": "Post description"
            }
        },
        "silent": true
    }
}

O método criará um comentário e, se necessário, o próprio chat para os msgid e conversation_id especificados, respectivamente. Os comentários serão criados no mesmo chat com mensagens pessoais, mas em conversas diferentes. Uma conversa será criada contendo todos os comentários do cliente para cada postagem comentada. A estrutura dos campos receiver e sender é a mesma para importar uma mensagem comum.

Editar uma mensagem

Este método também permite que você edite mensagens enviadas aos seus clientes. Você precisa passar o event_type: edit_message dentro da payload de mensagem:

{
  "event_type": "edit_message",
  "payload": {
    "timestamp": 1639605194,
    "msec_timestamp": 1639605194102,
    "msgid": "my_int-5f2836a8ca477",
    "conversation_id": "my_int-d5a421f7f217",
    "message": {
      "type": "text",
      "text": "Mensagem editada"
    }
  }
}

Cabeçalhos e tipo de autorização

Parâmetro	Tipo de dado	Descrição
Date	string	Data e hora em que a solicitação foi gerada. A assinatura será válida por 15 minutos a partir dessa data. A data deve estar no formato `Thu, 01 Jan 2023 12:00:00 +0000` (RFC2822).
Content-type	string	Tipo de dados da solicitação. Atualmente, apenas application/json é suportado.
Content-MD5	string	Para o corpo da solicitação, é necessário calcular o hash MD5 e indicá-lo no cabeçalho em letras minúsculas. Ao mesmo tempo, é importante lembrar que o corpo da solicitação é calculado como um fluxo de bytes, sem considerar o final da marcação JSON, e se houver “\n” ou espaços no final, eles também serão levados em conta.
X-Signature	string	Assinatura da solicitação como uma string. Ela é formada a partir do nome do método (GET/POST) em maiúsculas, com os valores dos cabeçalhos concatenados por “\n”. Os valores dos cabeçalhos são organizados em uma ordem específica. Se não houver cabeçalho, uma string vazia é especificada em seu lugar. Em seguida, adicione o caminho solicitado da URL sem o protocolo e o domínio (sem parâmetros GET) à string. A string resultante é calculada usando HMAC-SHA1 e, como segredo, utilizamos a chave secreta do canal obtida durante o registro. O hash resultante, em letras minúsculas, é indicado no cabeçalho X-Signature.

Cabeçalho de tipo de dado quando a solicitação é bem-sucedida
Content-Type: application/hal+json

Parâmetros de resposta

O método retorna o amojo_id da mensagem que aparecerá no feed do chat quando processada.

Parâmetro	Tipo de dado	Descrição
new_message[msgid]	string	ID da mensagem na API de Chats
new_message[ref_id]	string	ID do chat no lado da integração
new_message[conversation_id]	string	ID do chat na API de chats
new_message[sender_id]	string	ID do remetente da mensagem na API de Chats
new_message[receiver_id]	string	ID do destinatário da mensagem na API de Chats