Descripción
Ten en cuenta que no podrás ejecutar este paso directamente en la sección de Referencia de la API debido a limitaciones de la herramienta: no es posible calcular los encabezados requeridos y enviar una solicitud al mismo tiempo.
Este método permite enviar mensajes entrantes y salientes, o importar mensajes que fueron enviados desde una aplicación de terceros.
Ejemplo de un mensaje
El método generará un mensaje y, si es necesario, también creará el chat correspondiente para el msgid y conversation_id especificados.
| Tipo de mensaje | Caso de uso | Parámetros que deben pasarse |
|---|---|---|
Entrante de: cliente | Un cliente envía un mensaje al canal conectado. | Solo se completa el campo payload[sender], no se envía el campo payload[receiver]. |
Saliente de: usuario de Kommo | Un asesor escribe un mensaje al cliente y podemos identificar quién lo envía. | Se completan los campos payload[sender](información del asesor) y payload[receiver](información del cliente).Se pasa el ID del usuario de Kommo en payload[sender][ref_id] (puede obtenerlo a través de la solicitud de lista de usuarios aplicando el parámetro de consulta ?with=amojo_id). |
Saliente de: bot de la integración | Un asesor escribe un mensaje al cliente pero no podemos identificar al remitente. | Se completan los campos payload[sender] (información del bot) y payload[receiver] información del cliente).El ID del bot de la integración, que se obtuvo al registrar el canal en la API de Chat, se pasa en el campo payload[sender][ref_id]. |
Utilizando este método de la API, puedes importar en masa mensajes antiguos a un chat.
Recomendamos realizar la importación sin enviar notificaciones a los asesores ni crear un lead entrante para los mensajes, excepto para el último (el más reciente).
Para hacer esto, debes pasar el parámetro en el cuerpo payload[silent] con el valor true para todos los mensajes, excepto para el último, al cual se le pasa el valor false en payload[silent]. De esta forma, se creará un lead entrante solo para el último mensaje, y solo se enviará una notificación. Así evitaremos generar una interrupción innecesaria para el usuario.
{
"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": "[email protected]"
},
"profile_link": "https://example.com/profile/example.client",
"name": "Nombre del cliente"
},
"message": {
"type": "text",
"text": "Mensaje de un 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": "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": "Nombre del cliente",
"profile": {
"phone": "+1400000000",
"email": "[email protected]"
},
"profile_link": "https://example.com/profile/example.client"
},
"message": {
"type": "text",
"text": "Mensaje de un gerente 76fc2bea-902f-425c-9a3d-dcdac4766090"
},
"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": "Nombre del cliente",
"profile": {
"phone": "+1400000000",
"email": "[email protected]"
},
"profile_link": "https://example.com/profile/example.client"
},
"message": {
"type": "text",
"text": "Mensaje del bot del canal f1910c7f-b1e0-4184-bd09-c7def2a9109a"
},
"silent": true
}
}Cuando se importan mensajes desde el bot de integración, no se envían hooks.
Enviar un comentario
El método también te permite transferir comentarios entrantes y salientes (respuestas a comentarios que fueron enviados desde una aplicación externa)
La principal diferencia entre enviar comentarios y enviar mensajes es la adición de un campo post en la solicitud, que contiene el ID de la publicación en el lado de la integración.
{
"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": "[email protected]"
},
"profile_link": "https://example.com/profile/example.client",
"name": "Nombre del cliente"
},
"message": {
"type": "text",
"text": "Mensaje del 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": "creador de la publicación",
"caption": "Descripción de la publicación"
}
},
"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": "Nombre del administrador",
"ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
},
"receiver": {
"id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
"avatar": "https://example.com/users/avatar.png",
"name": "Nombre del cliente",
"profile": {
"phone": "+1234567890",
"email": "[email protected]"
},
"profile_link": "https://example.com/profile/example.client"
},
"message": {
"type": "text",
"text": "Comentario de un administrador 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": "creador d ela publicación",
"caption": "Descripción de la publicación"
}
},
"silent": true
}
}
El método creará un comentario y, si es necesario, también el chat correspondiente para los valores especificados en msgid y conversation_id, respectivamente. Los comentarios se crearán en el mismo chat que los mensajes personales, pero en conversaciones distintas. Se generará una conversación que agrupe todos los comentarios del cliente para cada publicación comentada. La estructura de los campos receiver y sender es la misma que se utiliza para importar un mensaje común.
Editar un mensaje
El método también te permite editar los mensajes enviados a tus clientes. Necesitas pasar event_type: edit_message en el payload del mensaje.
{
"event_type": "edit_message",
"payload": {
"timestamp": 1639605194,
"msec_timestamp": 1639605194102,
"msgid": "my_int-5f2836a8ca477",
"conversation_id": "my_int-d5a421f7f217",
"message": {
"type": "text",
"text": "Mensaje editado"
}
}
}Encabezados y tipo de autorización
| Parámetro | Tipo de dato | Descripción |
|---|---|---|
| Date | string | Fecha y hora en que se generó la solicitud. La firma será válida durante 15 minutos a partir de esta fecha. La fecha debe estar en el formato “Jue, 01 ene 2023 12:00:00 +0000” (RFC2822). |
| Content-type | string | Tipo de datos de la solicitud. Actualmente, solo se admite application/json. |
| Content-MD5 | string | Para el cuerpo de la solicitud, es necesario calcular el hash MD5 e indicarlo en el encabezado en minúsculas. Al mismo tiempo, es importante tener en cuenta que el cuerpo de la solicitud se calcula como un flujo de bytes sin considerar el final de la marca de JSON, y si hay \n o espacios al final, también se tomarán en cuenta. |
| X-Signature | string | Firma de la solicitud como una cadena. Se forma a partir del nombre del método (GET/POST) en mayúsculas, con los valores de los encabezados concatenados por \n. Los valores de los encabezados deben seguir un orden específico. Si no hay encabezado, se debe especificar una cadena vacía en su lugar. Luego, añade el camino solicitado de la URL sin el protocolo y dominio (sin los parámetros GET) a la línea. La cadena resultante se calcula utilizando HMAC-SHA1, y como secreto, se utiliza el secreto del canal obtenido durante el registro. El hash resultante en minúsculas se indica en el encabezado X-Signature. |
Encabezado de tipo de datos cuando la solicitud es exitosa/en caso de un error
Content-Type: application/json.
Parámetros de respuesta
| Parámetro | Tipo de dato | Descripción |
|---|---|---|
| new_message[msgid] | string | ID del mensaje en la API de Chats. |
| new_message[ref_id] | string | ID del chat en el lado de la integración |
| new_message[conversation_id] | string | ID de chat en la API de chats |
| new_message[sender_id] | string | ID del remitente en la API de Chats |
| new_message[receiver_id] | string | ID del receptor en la API de Chats |