Desarrolladores

API

Message Gateway API

Integración de módulos de transporte con soporte para la creación y el envío de plantillas de WhatsApp Business

Integración de módulos de transporte con soporte para la creación y el envío de plantillas de WhatsApp Business

Copiar enlace al artículo

Copiado

Contenido

Descripción y configuración del canal
- Tipos y componentes de las plantillas
- Políticas de envío y creación
Gestión de plantillas
Envío de mensajes de plantilla
Plantillas con archivos adjuntos

Descripción y configuración del canal

La creación de plantillas de mensajes simplifica la interacción habitual con los clientes:

permite estandarizar mensajes de texto y multimedia;
admite variables para personalizar los mensajes con el nombre del cliente u otros datos;
ayuda a mantener un estilo de comunicación uniforme;
permite editar las plantillas existentes desde el sistema conforme a los requisitos y comentarios del proveedor.

Tipos y componentes de las plantillas

El sistema admite plantillas de texto y multimedia. Ambos tipos incluyen un cuerpo de texto y admiten expresiones Twig, que se calculan al enviar el mensaje desde el sistema.

Las plantillas multimedia permiten añadir un encabezado de texto o un archivo adjunto: una imagen, un documento o un vídeo. El encabezado de texto también admite expresiones Twig; por ejemplo, puede incluir el nombre del cliente.

Además, una plantilla multimedia puede contener:

hasta 10 botones de respuesta rápida;
botones para abrir una URL;
botones para realizar una llamada.

El payload de los botones con enlace también puede parametrizarse mediante expresiones Twig.

La descripción detallada de los componentes estructurales disponibles se encuentra en la documentación de plantillas de WhatsApp Business.

Políticas de envío y creación

El uso de plantillas requiere que el módulo de transporte admita esta funcionalidad.

Para permitir el envío de mensajes de plantilla, al crear o actualizar la configuración del canal debe especificarse al menos uno de estos ajustes:

sending_policy.after_reply_timeout = 'template';
sending_policy.new_customer = 'template'.

El ajuste sending_policy.after_reply_timeout controla el envío después de que finalice la ventana de respuesta y admite los valores siguientes:

no: el agente no puede continuar la comunicación desde el sistema una vez finalizada la ventana de respuesta del diálogo;
template: se permite enviar un mensaje de plantilla una vez agotado el plazo asignado al agente, indicado en reply_deadline al enviar el mensaje.

El ajuste sending_policy.new_customer controla el primer mensaje enviado por el agente a un cliente y admite estos valores:

no: no se permite iniciar un diálogo por número de teléfono con un cliente que todavía no existe;
text: se permite enviar un mensaje de texto;
template: se permite enviar un mensaje de plantilla.

Para activar la creación de plantillas en el sistema, al crear o actualizar la configuración del canal debe establecerse settings.template.creation = true. Cuando se conecta al menos un canal con este ajuste, el formulario para crear y editar plantillas queda disponible en Ajustes → Plantillas de chat → Añadir.

Gestión de plantillas

Las plantillas pueden crearse o editarse desde la interfaz del sistema y desde el proveedor. El módulo de transporte debe procesar los webhooks correspondientes y transmitir al sistema los cambios de estado recibidos del proveedor.

Creación de una plantilla de chat en la interfaz del sistema

Cuando se crea una plantilla en el sistema, el módulo de transporte recibe un webhook de tipo template_create. La URL del webhook se indica al configurar el módulo de integración, como se describe en el artículo sobre la integración de un módulo de transporte.

Ejemplo del cuerpo de la solicitud enviada al webhook:

{
  "type": "template_create",
  "meta": {
    "timestamp": 1704878609
  },
  "data": {
    "name": "greeting_template",
    "lang": "ru",
    "category": "marketing",
    "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
    "header": {
      "content": {
        "body": "{{1}}, thank you for your order!",
        "type": "text"
      }
    },
    "footer": "Thank you for being with us!",
    "buttons": {
      "items": [
        {
          "label": "Our website",
          "url": "<http://site.com/profile/{{1}}>",
          "type": "url"
        },
        {
          "label": "Our phone number",
          "phone": "79998887766",
          "type": "phone"
        },
        {
          "label": "Amazing!",
          "type": "plain"
        }
      ]
    },
    "example": {
      "body": [
        "ORDER-123"
      ],
      "header": [
        "Alex"
      ],
      "buttons": [
        [
          "111"
        ],
        []
      ]
    },
    "channel_id": 1
  }
}

En la respuesta, el transporte debe devolver un código único que se utilizará para identificar la plantilla. Su estructura no está regulada, pero el código debe ser único dentro del canal.

Ejemplo de respuesta HTTP del transporte:

{
  "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en"
}

Después de recibir el webhook, el transporte debe enviar la plantilla al proveedor para su verificación. Hasta que se reciba la aprobación o el rechazo, la plantilla permanece en el sistema con el estado «En verificación». El plazo de espera puede alcanzar 2 días laborables.

Cambio del estado de verificación

Cuando el proveedor aprueba o rechaza la plantilla, el módulo de transporte debe enviar su estado actualizado al sistema mediante el método PUT /channels/{channel_id}/templates/{template_code} de Transport API.

Ejemplo del cuerpo de la solicitud HTTP:

{
  "name": "greeting_template",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "rejected",
  "rejection_reason": "scam",
  "header": {
    "content": {
      "type": "text",
      "body": "{{1}}, thank you for your order!"
    }
  },
  "footer": "Thank you for being with us!",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "<http://site.com/profile/{{1}}>"
      },
      {
        "type": "phone",
        "label": "Our phone number",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

El campo verification_status admite los valores siguientes:

approved: el proveedor ha aprobado la plantilla y esta puede utilizarse para enviar mensajes;
pending: la plantilla está pendiente de aprobación;
rejected: el proveedor ha rechazado la plantilla.

Una plantilla aprobada queda disponible para los disparadores, los envíos masivos, el envío manual en chats y otros escenarios.

En el formulario de una plantilla aprobada solo pueden modificarse determinados campos: los valores de las variables del encabezado, el cuerpo y los botones. También puede indicarse el evento del sistema que permitirá enviar la plantilla. Estas restricciones conservan su estructura y contenido, mientras que las variables y los eventos permiten adaptar el mensaje a cada escenario.

Si el proveedor rechaza la plantilla, el módulo puede transmitir el motivo mediante rejection_reason. Se admiten los valores siguientes:

abusive_content: la plantilla contiene material ofensivo, lenguaje soez u otro contenido abusivo;
incorrect_category: la categoría de la plantilla es incorrecta; consulte la documentación de categorías de WhatsApp Business;
invalid_format: el formato de la plantilla es incorrecto;
scam: el transporte ha identificado el contenido como fraudulento.

La plantilla rechazada no está disponible para el envío y se muestra con el estado correspondiente. Si el transporte proporciona un error de verificación, también se muestra su descripción textual.

Edición de una plantilla

Una plantilla rechazada puede editarse para adaptarla a las reglas del proveedor y enviarse de nuevo a verificación. Cuando se edita una plantilla existente, el módulo de transporte recibe un webhook de tipo template_update.

Ejemplo del cuerpo de la solicitud:

{
  "type": "template_update",
  "meta": {
    "timestamp": 1704881744
  },
  "data": {
    "name": "greeting_template",
    "lang": "ru",
    "category": "marketing",
    "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
    "header": {
      "content": {
        "body": "{{1}}, thank you for your order!",
        "type": "text"
      }
    },
    "footer": "Thank you for being with us!",
    "buttons": {
      "items": [
        {
          "label": "Our website",
          "url": "<http://site.com/profile/{{1}}>",
          "type": "url"
        },
        {
          "label": "Our phone number",
          "phone": "79998887766",
          "type": "phone"
        },
        {
          "label": "Amazing!",
          "type": "plain"
        }
      ]
    },
    "example": {
      "body": [
        "ORDER-123"
      ],
      "header": [
        "Alex"
      ],
      "buttons": [
        [
          "111"
        ],
        []
      ]
    },
    "channel_id": 1,
    "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en"
  }
}

Después de actualizar la plantilla, el módulo de transporte debe procesar el estado de verificación de la misma forma que durante su creación.

Creación y edición de plantillas en el proveedor

Las plantillas también pueden crearse y editarse desde el proveedor. Para transmitir al sistema una plantilla creada allí, se utiliza el método POST /channels/{channel_id}/templates de Transport API.

Ejemplo del cuerpo de la solicitud HTTP:

{
  "code": "GREETING_TEMPLATE",
  "name": "Greeting",
  "type": "media",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "approved",
  "header": {
    "content": {
      "type": "image"
    }
  },
  "examples": {
    "header": [
      "<https://image.com/image>"
    ],
    "body": [
      "ORDER-123"
    ]
  },
  "footer": "Thank you for being with us",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "<https://website.com/profile/{{1}}>"
      },
      {
        "type": "phone",
        "label": "Our phone",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

Copia y eliminación de una plantilla

Una plantilla puede copiarse para reutilizarla. En una copia pueden cambiarse los argumentos de las variables Twig o el evento utilizado para enviar la plantilla. Todas las copias creadas en el sistema permanecen vinculadas a una misma plantilla del transporte.

Cuando se elimina la última copia vinculada a una plantilla del transporte, esa plantilla también se elimina. El módulo de transporte recibe entonces un webhook de tipo template_delete.

Ejemplo del cuerpo del webhook:

{
  "type": "template_delete",
  "meta": {
    "timestamp": 1704882331
  },
  "data": {
    "channel_id": 1,
    "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en",
    "lang": "ru"
  }
}

Envío de mensajes de plantilla

Una vez aprobada la plantilla en el transporte, puede utilizarse para enviar mensajes desde el sistema. El transporte debe admitir el formato que incluye el encabezado, el pie de página y los botones.

Cuando se envía un mensaje de plantilla, el módulo de transporte recibe un webhook message_sent. Ejemplo para una plantilla con campos multimedia:

{
  "type": "message_sent",
  "meta": {
    "timestamp": 1704882857
  },
  "data": {
    "external_user_id": "79998887766",
    "external_chat_id": "",
    "channel_id": 1,
    "type": "text",
    "content": "Max, thank you for your order!\n\nOrder #ORDER-111 has been successfully placed. Thank you for your purchase!\n\nThank you for being with us!",
    "quote_external_id": null,
    "quote_content": null,
    "in_app_id": 1000,
    "user": {
      "id": 216,
      "first_name": "Ilya",
      "last_name": "",
      "avatar": ""
    },
    "customer": {
      "first_name": "",
      "last_name": "",
      "avatar": ""
    },
    "template": {
      "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en",
      "variables": {
        "header": {
          "type": "text",
          "args": [
            "Max"
          ]
        },
        "body": {
          "args": [
            "ORDER-111"
          ]
        },
        "buttons": [
          {
            "type": "url",
            "title": "Our website",
            "args": [
              "987"
            ]
          },
          {
            "type": "phone",
            "title": "Our phone number"
          },
          {
            "type": "plain",
            "title": "Amazing!"
          }
        ]
      }
    },
    "attachments": {
      "suggestions": [
        {
          "type": "url",
          "title": "Our website",
          "payload": "<http://site.com/profile/987>"
        },
        {
          "type": "phone",
          "title": "Our phone number",
          "payload": "79998887766"
        },
        {
          "type": "text",
          "title": "Amazing!"
        }
      ]
    }
  }
}

Plantillas con archivos adjuntos

En una plantilla cuyo encabezado contiene un archivo, no se transmite un header con texto. La definición de la plantilla declara el tipo multimedia mediante header.content.type; al enviar el mensaje, la información del archivo se transmite en template.variables.header.attachments y en data.items, como se muestra en los ejemplos.

Se admiten los siguientes formatos y tamaños:

Tipo de adjunto	Formatos permitidos	Tamaño máximo
Documento	`pdf`	100 MB
Imagen	`jpeg`, `jpg`, `png`	5 MB
Vídeo	`mp4`	16 MB

Los identificadores de tipo admitidos son:

image: imagen;
document: documento;
video: vídeo.

Ejemplo de los datos de una plantilla multimedia utilizados durante su creación con template_create:

{
  "code": "GREETING_TEMPLATE",
  "name": "Greeting",
  "type": "media",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "approved",
  "header": {
    "content": {
      "type": "image"
    }
  },
  "examples": {
    "header": [
      "https://image.com/image"
    ],
    "body": [
      "ORDER-123"
    ]
  },
  "footer": "Thank you for being with us",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "https://website.com/profile/{{1}}"
      },
      {
        "type": "phone",
        "label": "Our phone",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

Ejemplo de una solicitud para actualizar una plantilla multimedia mediante PUT /channels/{channel_id}/templates/{template_code}:

{
  "name": "Template name",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "rejected",
  "rejection_reason": "scam",
  "header": {
    "content": {
      "type": "image"
    }
  },
  "footer": "Thank you for being with us!",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "http://site.com/profile/{{1}}"
      },
      {
        "type": "phone",
        "label": "Our phone number",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

Ejemplo del webhook message_sent al enviar un mensaje de plantilla con una imagen adjunta:

{
  "type": "message_sent",
  "meta": {
    "timestamp": 1704889793
  },
  "data": {
    "external_user_id": "79998887766",
    "external_chat_id": "",
    "channel_id": 83,
    "type": "image",
    "content": "Order #ORDER-111 has been successfully placed. Thank you for your purchase!\n\nThank you for being with us!",
    "quote_external_id": null,
    "quote_content": null,
    "in_app_id": 1000,
    "user": {
      "id": 216,
      "first_name": "Ilya",
      "last_name": "",
      "avatar": ""
    },
    "customer": {
      "first_name": "",
      "last_name": "",
      "avatar": ""
    },
    "items": [
      {
        "id": "bfd530ae-42e7-4a10-94fb-d56383afcac4",
        "size": 87346,
        "caption": "demo_file.jpg",
        "height": 900,
        "width": 900
      }
    ],
    "template": {
      "variables": {
        "header": {
          "type": "image",
          "attachments": [
            {
              "id": "bfd530ae-42e7-4a10-94fb-d56383afcac4",
              "caption": "demo_file.jpg"
            }
          ]
        },
        "body": {
          "args": [
            "ORDER-111"
          ]
        },
        "buttons": [
          {
            "type": "url",
            "title": "Our website",
            "args": [
              "987"
            ]
          },
          {
            "type": "phone",
            "title": "Our phone number"
          },
          {
            "type": "plain",
            "title": "Amazing!"
          }
        ]
      }
    },
    "attachments": {
      "suggestions": [
        {
          "type": "url",
          "title": "Our website",
          "payload": "http://site.com/profile/987"
        },
        {
          "type": "phone",
          "title": "Our phone number",
          "payload": "79998887766"
        },
        {
          "type": "text",
          "title": "Amazing!"
        }
      ]
    }
  }
}

Gracias por tus comentarios.

¿Te resultó útil este artículo

Artículo anterior

Bot API

Artículo siguiente

Reacciones en chats de Simla.com

En Simla.com es posible gestionar las reacciones a los mensajes de chat. Los usuarios del sistema y los clientes pueden añadir, actualizar o eliminar reacciones en forma de emoji.

Integración de módulos de transporte con soporte para la creación y el envío de plantillas de WhatsApp Business Copiar enlace al artículo Copiado