Skip to main content

​
En resumen

  • Escribe {{key}} en la copia. En el momento del envío Notifique completa los valores predeterminados, el contacto y solicite variables.
  • Teclas de contacto: utilice name, email, phone. Prefiero el inglés para las claves integradas.
  • Administración y envío utilizan ámbitos diferentes. Consulte Ámbitos de clave API.

​
Canales en una plantilla

Cada plantilla elige qué canales están activos (1 a 7): sms, whatsapp, telegram, email, rcs, push, voice. En la API, use un bloque raíz por canal: On send, channels must be a subset of enabledChannels. A requested but disabled channel returns 400 (TEMPLATE_CHANNEL_NOT_ENABLED).

​
Per-channel payloads (create / update)

{{…}} variables also apply inside nested RCS strings, push title/body, and voice speakText.

​
Variables in copy ({{…}})

Two sources merge on send:
  1. From the template: placeholders you typed. They need a value in variables or variableDefaults.
  2. From the contact: filled automatically when the recipient exists in the workspace (except Telegram-only recipients).
Priority order: template defaults → contact data → custom fields → request variables (wins).

​
Built-in contact keys

Prefer {{name}}. In some internal flows nome may be filled alongside name, but the stable API and editor contract is name. Send variables.nome only if your copy intentionally uses that key.
Telegram-only recipients (chat_id or @username): automatic name/email merge does not run. Fill via variables or defaults.

​
Accepted formats

  • Named: {{order}} → variables: { "order": "123" }
  • Positional: {{1}}, {{2}} → keys "1", "2"
  • Custom fields: same CRM technical key, e.g. {{current_plan}}

​
Custom fields

Each field has a technical key (snake_case, e.g. current_plan). In the template: {{current_plan}} with the same key. Define them in the dashboard (Contacts → Custom fields) or via the Contacts API. After merge, values also apply to RCS, Push, and Voice.

​
Defaults (variableDefaults)

If the send does not provide a key, the template default is used before failing on a missing variable. Contact data and request variables can still override it.

​
Marketing and preferences

For templates with category MARKETING:
  • marketingTopicId: ties the send to a communication topic
  • appendPreferencesLink (default true): the platform fills {{preferences_link}} per recipient
Outside marketing, preferences_link may be empty: do not rely on it as the only CTA.

​
Translations (localeTranslations)

Puede almacenar traducciones por locale para campos de canales habilitados. Al enviar, la API elige la copia según la preferencia de idioma del contacto cuando esté disponible. Los marcadores {{…}} en traducciones deben coincidir con la plantilla principal.

​
Management via API

List query: page, limit, search (name). Minimal SMS-only example:
templates:* scopes are for management. On send, each channel needs its send scope (including voice:call for voice).

​
Metaplantillas oficiales (WHATSAPP_OFFICIAL)

POST /v1/templates y PATCH /v1/templates/:id utilizan las mismas validaciones que el panel:
  • medios requeridos en el encabezado/carrusel (META_TEMPLATE_MEDIA_REQUIRED)
  • tarjetas de carrusel con la misma estructura (META_TEMPLATE_CAROUSEL_INCONSISTENT)
  • estructura rica solo en plantillas oficiales (TEMPLATE_META_STRUCTURE_REQUIRES_OFFICIAL)
Al enviar (POST /v1/templates/send o type: "template" en cada ruta de canal) con sk_live_, la API también valida el Meta token, metaName, los medios y el carrusel antes de hacer cola cuando el canal es WhatsApp oficial. Con sk_test_, esas Meta puertas no se ejecutan (consulte Sandbox). Cada ruta de canal (POST /v1/sms/messages, /v1/email/messages, /v1/whatsapp/messages, etc.) acepta type: "template" + payload.templateId y activa sólo ese canal, lo que resulta útil cuando ya utiliza el contrato de canal nativo. El name interno puede diferir de metaName (nombre del gráfico). Sin un metaName → META_TEMPLATE_NOT_FOUND resoluble. Códigos completos: Respuestas de error (Meta Cloud / plantillas oficiales acordeón) y Metaplantillas oficiales. Esquemas completos: Referencia de API en la pestaña Plantillas.

​
Ver también