urEsta API (sigla en inglés de Interfaz de Programación de Aplicaciones) permite la integración entre sus aplicaciones con el servicio de envío de Plantillas de Atom. Esta API permite:
- Enviar una plantilla.
- Obtener un listado de plantillas.
- Ver detalles de una plantilla a través de su ID.
Endpoint: Templates - Envío de Plantilla
Este servicio permite el envío de Templates Messages utilizando el número de WhatsApp Oficial y el templateId.
Cuando el número enviado ya se encuentre vinculado con una conversación, se enviará el mensaje sobre la misma y la confirmación de envío será inmediata. En caso contrario, se esperará confirmación por medio del proveedor de WhatsApp Oficial, por lo cual no se brindará una confirmación de envío inmediata.
Parámetros
A continuación explicamos los parámetros que se deben incluir dentro de la petición de manera obligatoria, y otros que se pueden agregar opcionalmente:
|
Nombre del Parámetro |
Descripción |
Tipo de Dato |
Requerido |
|
templateId |
Identificador (Id) del Template Message de AtomChat. |
string |
Sí |
|
phoneNumber |
Número de teléfono al que se enviará el Template Message. Se debe anteponer el código del país, sin utilizar el signo + Correcto: 50755667788 ✅ Incorrecto: +50555667788 ❌ Incorrecto: 55667788 ❌ |
string |
Sí |
|
clientName |
Nombre del cliente al que se le enviará el Template Message. |
string |
Sí. El valor por defecto será el número de teléfono. |
|
groupName |
Nombre del grupo a asignar. |
string |
No. El valor por defecto se obtiene del primer grupo asociado a la integración. |
|
assign |
Indica si la conversación se debe asignar a un Agente (con el valor true). En caso contrario, es asignada a Bot. |
boolean |
No. El valor por defecto es false. |
|
params |
Colección de parámetros con sus valores requeridos para el uso del Template Message. {key: value} |
object |
No |
La petición para realizar el envío de Templates Messages (mensajes con plantillas) utilizando la nueva API de AtomChat, se realiza de la siguiente manera:
|
Tipo de Conexión |
Acceso público por Internet |
|
Endpoint |
https://us-central1-atomchat-io.cloudfunctions.net/templates |
|
Método |
POST |
|
Encabezados |
Content-type: application/json Charset: utf-8 Authorization: Bearer (token público) |
|
Cuerpo |
{ “templateId”: “id_del_template”, “phoneNumber”: “numero_de_telefono”, “clientName”: “nombre_del_cliente”, “groupName”: “nombre_del_grupo”, “assign”: true/false, “params”: { “param1”: “valor”, “param2”: “valor ”, … }, } |
Respuestas
Las respuestas esperadas para la petición realizada, son las siguientes:
|
Escenario |
Código de Respuesta |
Cuerpo de la Respuesta |
|
Plantilla enviada |
200 |
{ success: true, message: "Sent", data: {conversation_id : conversation.id } } |
|
Plantilla pendiente de envío |
202 |
{ "success": false, "conversationId": conversation.id, "status": 202 } |
|
Parámetros incorrectos |
400 |
{ success: false, message: "No hay datos para enviar" } |
|
Faltan Parámetros de plantilla requeridos |
400 |
{ code: 400, body: { context: { key: 'Body', label: 'body.params' }, message: "Missing params:[] ", path: [ 'body.params' ], type: 'Bad format', }, } |
|
Plantilla sin ID o Plantilla sin mensaje definido |
400 |
{ code: 400, body: { context: { key: 'Body', label: ['template.appId', 'template.message'] }, message: 'No data to send', path: [ 'template.appId', 'template.message' ], type: 'Bad format', }, } |
|
Canal no conectado |
401 |
{ code: 401, body: { context: { value: atom.channel?.status, key: 'Channel', label: 'channel.status' }, message: 'The channel associated to the template is not configured yet, please contact the support team', path: ['channel.status'], type: 'Bad format', }, } |
|
Token incorrecto |
401 |
{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" } |
|
Se alcanzó el límite de conversaciones del plan |
401 |
{ "success": false, "message": "The client has reached conversations limit", "conversationId": null, "status": 401 } |
|
Error interno |
500 |
{ context: { key: 'Api', label: 'api.SendTemplateController', value: error }, message: 'Something went wrong while the operation was executed', path: ['api.SendTemplateController'], type: 'Internal Server Error', } |
Endpoint: Get List of templates - Listar plantillas
Este servicio permite listar las plantillas pertenecientes a un canal determinado por el token público.
Parámetros
A continuación explicamos los parámetros que se deben incluir dentro de la petición de manera obligatoria, y otros que se pueden agregar opcionalmente
|
Nombre del Parámetro |
Descripción |
Tipo de Dato |
Requerido |
|
page |
Indicador de la página sobre la cual se desea obtener los registros. Default: 1 |
string |
No |
|
size |
Cantidad de registros a recuperar. Default: 10 |
string |
No |
La petición para realizar la recepción de listado de plantillas utilizando la API de AtomChat, se realiza de la siguiente manera:
|
Tipo de Conexión |
Acceso público por Internet |
|
Endpoint |
'https://us-central1-atomchat-io.cloudfunctions.net/templates?page=1&size=1000&sort=asc' |
|
Método |
GET |
|
Encabezados |
Content-type: application/json Charset: utf-8 Authorization: Bearer (token público) |
Respuestas
Las respuestas esperadas para la petición realizada, son las siguientes:
|
Escenario |
Código de Respuesta |
Cuerpo de la Respuesta |
|
Listar plantillas |
200 |
{ length: int, page: int, items: [ { id: string, message: string, buttons: [], headerParams?: [clave: valor], status: APPROVED/REJECTED, active: boolean, createdAt: Date, updatedAt: Date, bodyParams: [], description: string } ] } |
|
Número existente |
200 |
{ success: true, message: "Sent", data: {conversation_id : conversation.id } } |
|
Token incorrecto |
400 |
{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" } |
|
Error interno |
500 |
{ "context":{ "key":"Template", "label":"template" }, "message":"Something went wrong while the operation was executed", "path":["template"], "type":"Internal Server Error" } |
Ejemplo de estructura JSON
{
"length": 2,
"page": 1,
"items": [
{
"id": "b5ssgNtFPa5Vbrb8TOxt",
"message": "Hola, Bienvenido a almacenes tia, siempre de todo a menor precio, siempre",
"buttons": [],
"status": "APPROVED",
"active": true,
"createdAt": "2022-06-02T18:49:32.786Z",
"updatedAt": "2022-06-29T17:21:01.098Z",
"bodyParams": [],
"description": "Plantilla Tia"
},
{
"id": "7gKfsuDayJeBqqSGfYIY",
"message": "Hola, 1 👋 Te saludamos desde *2* 🛒Vimos que te interesó uno de nuestros productos y *queremos que sea tuyo* 😉Te invitamos a volver a tu compra *en un clic* ✨👇3 ",
"buttons": [],
"status": "APPROVED",
"active": true,
"createdAt": "2022-06-04T02:29:43.652Z",
"updatedAt": "2022-06-04T16:38:13.083Z",
"bodyParams": [
"client_name",
"companyName",
"url"
],
"description": "shopify_abandoned_checkout"
}
]
}
Endpoint: Get Template by ID - Ver detalles de una plantilla
Este servicio permite obtener los detalles pertenecientes a una plantilla en particular.
La petición para realizar la recepción de listado de plantillas utilizando la API de AtomChat, se realiza de la siguiente manera:
|
Tipo de Conexión |
Acceso público por Internet |
|
Endpoint |
https://us-central1-atomchat-io.cloudfunctions.net/api/Template/{templateId} |
|
Método |
GET |
|
Encabezados |
Content-type: application/json Charset: utf-8 Authorization: Bearer (token público) |
Respuestas
Las respuestas esperadas para la petición realizada, son las siguientes:
|
Escenario |
Código de Respuesta |
Cuerpo de la Respuesta |
|
Plantilla recuperada |
200 |
{ id: string, message: string, buttons: [], status: APPROVED/REJECTED, active: true/false, createdAt: string, updatedAt: string, bodyParams: [], description: string } |
|
Plantilla inexistente |
404 |
{ "code": 404, "body": { "context": { "key": "Template", "label": "template", "value": id.template }, "message": "Cannot find the template with id = templateId", "path": [ "template" ], "type": "Not Found" } } |
|
Token incorrecto |
400 |
{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" } |
Ejemplo de estructura JSON
{
"id": "b5ssgNtFPa5Vbrb8TOxt",
"message": "Hola, Bienvenido a almacenes tia, siempre de todo a menor precio, siempre",
"buttons": [],
"status": "APPROVED",
"active": true,
"createdAt": "2022-06-02T18:49:32.786Z",
"updatedAt": "2022-06-29T17:21:01.098Z",
"bodyParams": [],
"description": "Plantilla Tia"
}