> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Envía plantillas y Flows de WhatsApp desde Customer.io

> Envía plantillas y Flows de WhatsApp aprobados desde campañas de Customer.io con la API de Flowella y, si quieres, sincroniza los mensajes entrantes.

Flowella se conecta con Customer.io a través de las acciones de webhook de Customer.io y la API REST de Flowella. Una campaña de Customer.io llama a Flowella para enviar una plantilla de WhatsApp aprobada, incluidas las plantillas con un botón de WhatsApp Flow, a cada persona que llega a ese paso. Si también quieres las respuestas de WhatsApp en Customer.io, Flowella puede enviar cada mensaje entrante a una automatización de Customer.io activada por webhook que tú controlas.

> [!NOTE]
>
> No hay ninguna app que instalar en Customer.io. Construyes ambas direcciones con acciones estándar de Customer.io, así que decides exactamente qué solicitudes se ejecutan y qué atributos cambian.

## Cómo funciona la integración

| Dirección | Qué se ejecuta | Qué cambia |
| - | - | - |
| De Customer.io a Flowella | Una acción **Send and receive data** (webhook) de tu campaña llama a `POST /v1/templates/send` para la persona de la campaña. | Flowella pone en cola un mensaje de plantilla de WhatsApp. No se escribe nada en Customer.io. |
| De Flowella a Customer.io (opcional) | Un webhook saliente de Flowella envía eventos `message.received` a una automatización activada por webhook en Customer.io. | Solo los atributos de la persona que asignes en tu propia acción **Create or Update Person**. |

Flowella nunca llama a la API de Customer.io. En la dirección entrante opcional, Flowella solo envía eventos a la URL de webhook que le indiques, y tu automatización decide qué hacer con ellos.

```mermaid theme={null}
flowchart LR
    A["Customer.io: la persona llega a la acción de webhook"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: mensaje de WhatsApp entregado"]
    C --> D["El contacto responde en WhatsApp"]
    D --> E["Flowella: webhook message.received"]
    E --> F["Customer.io: automatización activada por webhook"]
    F --> G["Customer.io: Create or Update Person"]
```

## Antes de empezar

* Una organización de Flowella con un número de WhatsApp conectado. Consulta [Orden de configuración](https://knowledge.flowella.io/es/whatsapp/accounts/setup-sequence.md).
* Una plantilla de WhatsApp aprobada en Flowella. Consulta [Plantillas](https://knowledge.flowella.io/es/app/templates.md).
* El rol **Owner** o **Admin** en Flowella, para crear una clave de API y, para la sincronización entrante, un webhook. Consulta [Equipo y roles](https://knowledge.flowella.io/es/settings/team.md).
* Un espacio de trabajo de Customer.io en el que puedas crear campañas o automatizaciones con acciones de webhook.
* El número de WhatsApp de cada persona guardado en su perfil de Customer.io en formato internacional, como `+447700900123`. Consulta [Formato de números de teléfono](https://knowledge.flowella.io/es/hubspot/phone-number-format.md).
* El consentimiento de cada persona para recibir mensajes de WhatsApp tuyos. Meta exige el opt-in antes de escribir a nadie. Consulta la [guía de opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in) de Meta.

## Envía una plantilla de WhatsApp desde Customer.io

**1. Crea una clave de API de Flowella**

En Flowella, ve a **Settings**, luego a **API keys**, y crea una clave live con un nombre como `Customer.io production`. Cópiala enseguida: Flowella solo la muestra una vez. Consulta [Claves de API](https://knowledge.flowella.io/es/settings/api-keys.md).

**2. Busca los ID de la plantilla y del canal**

Llama a `GET /v1/templates?status=APPROVED` con tu clave. Anota el `id` y el `wabaId` de la plantilla, y el `whatsappChannelId` del número desde el que quieres enviar. Consulta [Varios números](https://knowledge.flowella.io/es/essentials/multi-channel.md) si tienes más de un número.

```bash theme={null}
curl "https://api.flowella.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"
```

**3. Añade una acción de webhook a tu campaña**

En el workflow de tu campaña de Customer.io, añade una acción **Send and receive data** en el punto en que deba salir el mensaje de WhatsApp. Consulta la guía de Customer.io sobre [acciones de webhook](https://docs.customer.io/webhooks-action).

**4. Configura la solicitud**

Establece el método `POST` y la URL `https://api.flowella.io/v1/templates/send`. Añade estas cabeceras:

| Cabecera | Valor |
| - | - |
| `Authorization` | `Bearer ` seguido de tu clave de API de Flowella |
| `Content-Type` | `application/json` |

**5. Escribe el cuerpo de la solicitud**

Pega este cuerpo y sustituye los ID por los tuyos. Cambia `customer.phone` por el atributo que contiene el número de WhatsApp de la persona.

```json theme={null}
{
  "templateId": "1234567890123456",
  "templateWabaId": "102290129340398",
  "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "recipients": [
    {
      "phone": "{{customer.phone}}",
      "bodyParameters": ["{{customer.first_name}}"]
    }
  ]
}
```

`bodyParameters` rellena las variables del cuerpo de la plantilla en orden: el primer valor va en `{{1}}`, el segundo en `{{2}}`, y así sucesivamente. Déjalo como una lista vacía, `[]`, si la plantilla no tiene variables en el cuerpo.

**6. Prueba la acción**

Elige una persona de prueba con tu propio número de WhatsApp y selecciona **Test response** en Customer.io. Añade una cabecera `Idempotency-Key` con un valor que no hayas usado antes, como `test-2026-11-11-01`, y cámbialo en cada prueba. Consulta [Envíos repetidos e idempotencia](#repeat-sends-and-idempotency).

Una respuesta `202` con `"status": "accepted"` significa que Flowella puso el envío en cola. No confirma la entrega: consulta el resultado en la pestaña **Statistics** de la plantilla en Flowella.

**7. Quita la cabecera de prueba e inicia la campaña**

Elimina la cabecera `Idempotency-Key` que usaste para las pruebas, o sustitúyela por un valor distinto para cada persona. Después, inicia la campaña.

### Opciones de plantilla para cada persona

El cuerpo de la solicitud acepta estos campos para cada destinatario. La [introducción a la API](https://knowledge.flowella.io/es/api-reference/introduction.md) y el [documento OpenAPI](https://api.flowella.io/v1/openapi.json) describen la solicitud completa.

| Campo | Para qué sirve |
| - | - |
| `phone` | El número de WhatsApp de la persona. Obligatorio. |
| `bodyParameters` | Valores para las variables del cuerpo, en orden. Hasta 20. |
| `buttonParameters` | Valores para las variables de botones de URL (`subType` `url`), botones de Flow (`subType` `flow`) o botones de copiar código (`subType` `copy_code`). |

En una plantilla con encabezado de imagen, vídeo o documento, puedes indicar un enlace público al archivo en `headerMedia.url`, en el nivel superior del cuerpo.

### Envíos repetidos e idempotencia

`POST /v1/templates/send` te protege de enviar el mismo mensaje dos veces, algo importante porque Customer.io reintenta una acción de webhook cuando no recibe una respuesta `2xx`:

* Sin una cabecera `Idempotency-Key`, Flowella usa un hash del cuerpo de la solicitud como clave. Un cuerpo idéntico byte a byte en un plazo de 7 días devuelve el `id` original y no envía nada. Como el cuerpo de cada persona contiene su propio número, una campaña normal envía a todos una vez.
* Con una cabecera `Idempotency-Key`, cualquier solicitud con la misma clave en un plazo de 7 días devuelve el `id` original y no envía nada, aunque el cuerpo haya cambiado.
* Además, Flowella omite un segundo envío de la misma plantilla al mismo número en un plazo de 15 segundos.

> [!WARNING]
>
> Nunca dejes un valor fijo de `Idempotency-Key` en la acción de una campaña activa. Solo la primera persona recibe el mensaje: cada solicitud posterior reutiliza la clave, así que Flowella devuelve el primer `id` y no envía nada. Quita la cabecera antes de iniciar la campaña, o construye un valor distinto para cada persona, como el nombre de la campaña seguido de `{{customer.id}}`.

Estas mismas reglas explican la mayoría de las pruebas fallidas. Enviar de nuevo la misma plantilla a la misma persona de prueba produce el mismo cuerpo, así que Flowella no envía nada salvo que cambies el valor de `Idempotency-Key` cada vez.

### Envíos a un segmento grande

Cada solicitud de Customer.io pone en cola un envío, y Flowella lo entrega en segundo plano y reintenta los errores temporales de WhatsApp. En las campañas grandes se aplican dos límites:

* **El límite de mensajes de Meta.** Meta limita a cuántas personas puedes escribir fuera de la ventana de 24 horas en un periodo móvil de 24 horas. Consulta [Límites de mensajes](https://knowledge.flowella.io/es/whatsapp/limits/messaging-limits.md).
* **El límite de velocidad de tu clave de API.** Las solicitudes que superan el límite devuelven `429` con una cabecera `Retry-After`. Consulta [Límites de velocidad](https://knowledge.flowella.io/es/api-reference/introduction.md#rate-limits).

Reparte los envíos grandes con los controles de envío de Customer.io y sigue el progreso en la pestaña **Statistics** de la plantilla. Flowella omite a quien se haya dado de baja en el número desde el que envías. Consulta [Exclusiones](https://knowledge.flowella.io/es/app/opt-outs.md).

## Sincroniza los mensajes entrantes con Customer.io (opcional)

Esta parte envía a Customer.io cada mensaje de WhatsApp que te manda un contacto, para que puedas actualizar a la persona o iniciar otras campañas a partir de él.

**1. Crea una automatización activada por webhook en Customer.io**

Crea una campaña o automatización activada por webhook y copia la URL de webhook que genera Customer.io. Consulta la guía de Customer.io sobre [campañas activadas por webhook](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**2. Añade un webhook saliente en Flowella**

En Flowella, ve a **Settings**, luego a **Webhooks**, y selecciona **Add webhook**. Pega la URL de Customer.io en **Endpoint URL**, introduce un secreto de firma y marca solo `message.received` en **Events**. Consulta [Webhooks](https://knowledge.flowella.io/es/settings/webhooks.md).

**3. Envía datos de ejemplo**

Envíate una plantilla de WhatsApp desde Flowella y respóndela, para que Customer.io reciba un evento `message.received` real con el que construir el workflow. Cada evento tiene este aspecto:

```json theme={null}
{
  "id": "evt_3f2b8c1d9a7e4f60b5c2d8e1a4f7b9c3",
  "type": "message.received",
  "created_at": "2026-10-21T09:30:00.000Z",
  "payload_version": "1",
  "data": {
    "messageId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "contactId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "INBOUND",
    "type": "TEXT",
    "metaMessageId": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY"
  }
}
```

**Send test event** en Flowella envía un evento `webhook.test`, que no tiene contacto, así que fíltralo en el paso siguiente.

**4. Quédate solo con los mensajes entrantes reales**

Añade una **True/False Branch** que continúe solo cuando el `type` del disparador sea `message.received`.

**5. Busca el contacto en Flowella**

El evento contiene ID, no el número de teléfono. Añade una acción **Send and receive data** con el método `GET`, la URL `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}` y la misma cabecera `Authorization` que antes. La respuesta incluye `id`, `phone`, `waId`, `name`, `email`, `externalId`, `isOptedOut`, `createdAt` y `updatedAt` del contacto.

Para guardar el propio mensaje, añade otra solicitud a `GET /v1/messages/{{trigger.data.messageId}}`. Su campo `body` contiene el texto del mensaje y puede estar vacío.

**6. Actualiza a la persona**

Añade una acción **Create or Update Person**. Elige el identificador que usa tu espacio de trabajo para las personas y define solo los atributos que necesites, como la hora de la última respuesta por WhatsApp. Consulta la guía de Customer.io sobre [Create or update person](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> En una automatización activada por webhook, **Create or Update Person** crea una persona nueva cuando nadie coincide con el identificador. Para no crear personas que no quieres, añade una condición a la acción para que el paso solo se ejecute cuando el valor del identificador esté presente, y haz pruebas con un número que no esté en tu espacio de trabajo.

### Seguridad del webhook entrante

Flowella firma cada solicitud con la cabecera `X-Flowella-Signature`. Una automatización de Customer.io activada por webhook no puede comprobar esa firma, así que cualquiera que tenga la URL de webhook de Customer.io puede enviarle datos. Mantén la URL en privado y no uses la sincronización entrante para cambiar atributos de consentimiento o de facturación. Consulta [Verificar firmas](https://knowledge.flowella.io/es/api-reference/webhooks.md#verify-signatures) si primero diriges los eventos a tu propio endpoint.

### Exclusiones

Cuando un contacto envía `STOP` u otra palabra clave de exclusión, Flowella registra la exclusión en ese número de WhatsApp y bloquea todos los envíos posteriores a ese contacto desde él, incluidos los envíos desde Customer.io. Consulta [Exclusiones](https://knowledge.flowella.io/es/app/opt-outs.md).

Para copiar las exclusiones en Customer.io, no te bases en el evento `optout.created`: por ahora no se dispara con la primera exclusión de un contacto en un número. En su lugar, lista las exclusiones con `GET /v1/opt-outs`, que acepta los filtros `createdAfter` y `phone`.

## Solución de problemas

| Síntoma | Causa | Solución |
| - | - | - |
| `401` con `Invalid or expired API key` | La clave se revocó o se sustituyó, o se pegó mal. | Crea una clave nueva y actualiza la cabecera `Authorization`. Consulta [Claves de API](https://knowledge.flowella.io/es/settings/api-keys.md). |
| **Could not load API keys** en Flowella | Solo los Owners y los Admins pueden gestionar las claves de API. | Pide a un Owner o a un Admin que cree la clave. |
| `401` con `Missing bearer token` | La solicitud fue a `https://app.flowella.io/api/v1`, que redirige, y se perdió la cabecera. | Usa `https://api.flowella.io/v1`. |
| Una prueba devuelve `202` pero no llega nada | El cuerpo o la `Idempotency-Key` coincidían con un envío anterior de los últimos 7 días, o la misma plantilla fue al mismo número en menos de 15 segundos. | Usa un valor nuevo de `Idempotency-Key` en cada prueba. |
| Solo la primera persona de una campaña recibió el mensaje | Se dejó un valor fijo de `Idempotency-Key` en la acción. | Quita la cabecera o haz que su valor sea único para cada persona. |
| El envío muestra un fallo en la pestaña **Statistics** | Meta no pudo entregar el mensaje, por ejemplo porque el número no tiene WhatsApp. | Lee el motivo en la columna **Details**. Consulta [Códigos de error de Meta](https://knowledge.flowella.io/es/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** en la pestaña **Statistics** | El atributo de teléfono está vacío o no tiene formato internacional. | Guarda los números con el prefijo del país, como `+447700900123`. |
| Customer.io no recibe eventos entrantes | El webhook de Flowella está inactivo o `message.received` no está marcado. | Revisa el **Delivery log** del webhook en Flowella. Consulta [Webhooks](https://knowledge.flowella.io/es/settings/webhooks.md#delivery-log). |

## Relacionado

> [card] [Introducción a la API](https://knowledge.flowella.io/es/api-reference/introduction.md)
>
> Autenticación, idempotencia, límites de velocidad y errores.

> [card] [Referencia de webhooks](https://knowledge.flowella.io/es/api-reference/webhooks.md)
>
> Tipos de eventos, cuerpos de las solicitudes y firmas.

> [card] [Variables de plantilla](https://knowledge.flowella.io/es/app/template-variables.md)
>
> Variables, ejemplos y valores de respaldo.

> [card] [Envío masivo](https://knowledge.flowella.io/es/app/bulk-send.md)
>
> Envía una plantilla a una lista desde la app de Flowella.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.