> ## 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.

# Enviar modelos e Flows WhatsApp a partir do Customer.io

> Envie modelos e Flows WhatsApp aprovados a partir de campanhas Customer.io com a API do Flowella e, se quiser, sincronize as mensagens recebidas.

O Flowella liga-se ao Customer.io através das ações de webhook do Customer.io e da API REST do Flowella. Uma campanha Customer.io chama o Flowella para enviar um modelo WhatsApp aprovado, incluindo modelos com um botão de WhatsApp Flow, a cada pessoa que chega a esse passo. Se também quiser as respostas WhatsApp no Customer.io, o Flowella pode enviar cada mensagem recebida para uma automação acionada por webhook no Customer.io que é gerida por si.

> [!NOTE]
>
> Não há nenhuma aplicação para instalar no Customer.io. Constrói ambas as direções com ações padrão do Customer.io, por isso decide exatamente que pedidos são executados e que atributos mudam.

## Como funciona a integração

| Direção | O que é executado | O que altera |
| - | - | - |
| Do Customer.io para o Flowella | Uma ação **Send and receive data** (webhook) na sua campanha chama `POST /v1/templates/send` para a pessoa na campanha. | O Flowella coloca em fila uma mensagem de modelo WhatsApp. Nada é escrito no Customer.io. |
| Do Flowella para o Customer.io (opcional) | Um webhook de saída do Flowella envia eventos `message.received` para uma automação acionada por webhook no Customer.io. | Apenas os atributos da pessoa que mapear na sua própria ação **Create or Update Person**. |

O Flowella nunca chama a API do Customer.io. Na direção opcional de entrada, o Flowella apenas publica eventos no URL de webhook que lhe indicar, e a sua automação decide o que fazer com eles.

```mermaid theme={null}
flowchart LR
    A["Customer.io: a pessoa chega à ação de webhook"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: mensagem WhatsApp entregue"]
    C --> D["O contacto responde no WhatsApp"]
    D --> E["Flowella: webhook message.received"]
    E --> F["Customer.io: automação acionada por webhook"]
    F --> G["Customer.io: Create or Update Person"]
```

## Antes de começar

* Uma organização Flowella com um número WhatsApp ligado. Consulte [Sequência de configuração](https://knowledge.flowella.io/pt/whatsapp/accounts/setup-sequence.md).
* Um modelo WhatsApp aprovado no Flowella. Consulte [Modelos](https://knowledge.flowella.io/pt/app/templates.md).
* A função **Owner** ou **Admin** no Flowella, para criar uma chave de API e, para a sincronização de entrada, um webhook. Consulte [Equipa e funções](https://knowledge.flowella.io/pt/settings/team.md).
* Um espaço de trabalho Customer.io onde possa criar campanhas ou automações com ações de webhook.
* O número WhatsApp de cada pessoa guardado no respetivo perfil Customer.io em formato internacional, como `+447700900123`. Consulte [Formato do número de telefone](https://knowledge.flowella.io/pt/hubspot/phone-number-format.md).
* O consentimento de cada pessoa para receber mensagens WhatsApp suas. A Meta exige opt-in antes de enviar mensagens a alguém. Consulte as [orientações de opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in) da Meta.

## Enviar um modelo WhatsApp a partir do Customer.io

**1. Criar uma chave de API do Flowella**

No Flowella, aceda a **Settings** e depois **API keys**, e crie uma chave de produção com um nome como `Customer.io production`. Copie-a de imediato: o Flowella só a mostra uma vez. Consulte [Chaves de API](https://knowledge.flowella.io/pt/settings/api-keys.md).

**2. Encontrar os IDs do modelo e do canal**

Chame `GET /v1/templates?status=APPROVED` com a sua chave. Anote o `id` e o `wabaId` do modelo e o `whatsappChannelId` do número a partir do qual quer enviar. Consulte [Multicanal](https://knowledge.flowella.io/pt/essentials/multi-channel.md) se tiver vários números.

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

**3. Adicionar uma ação de webhook à campanha**

No fluxo de trabalho da sua campanha Customer.io, adicione uma ação **Send and receive data** no ponto em que a mensagem WhatsApp deve sair. Consulte o guia do Customer.io sobre [ações de webhook](https://docs.customer.io/webhooks-action).

**4. Configurar o pedido**

Defina o método como `POST` e o URL como `https://api.flowella.io/v1/templates/send`. Adicione estes cabeçalhos:

| Cabeçalho | Valor |
| - | - |
| `Authorization` | `Bearer ` seguido da sua chave de API do Flowella |
| `Content-Type` | `application/json` |

**5. Escrever o corpo do pedido**

Cole este corpo e substitua os IDs pelos seus. Altere `customer.phone` para o atributo que contém o número WhatsApp da pessoa.

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

`bodyParameters` preenche as variáveis do corpo do modelo por ordem: o primeiro valor vai para `{{1}}`, o segundo para `{{2}}`, e assim por diante. Deixe uma lista vazia, `[]`, se o modelo não tiver variáveis no corpo.

**6. Testar a ação**

Escolha uma pessoa de teste com o seu próprio número WhatsApp e selecione **Test response** no Customer.io. Adicione um cabeçalho `Idempotency-Key` com um valor que ainda não tenha usado, como `test-2026-11-11-01`, e altere-o em cada teste. Consulte [Envios repetidos e idempotência](#repeat-sends-and-idempotency).

Uma resposta `202` com `"status": "accepted"` significa que o Flowella colocou o envio em fila. Não confirma a entrega: verifique o resultado no separador **Statistics** do modelo no Flowella.

**7. Remover o cabeçalho de teste e iniciar a campanha**

Elimine o cabeçalho `Idempotency-Key` que usou nos testes, ou substitua-o por um valor diferente para cada pessoa. Depois, inicie a campanha.

### Opções do modelo que pode definir por pessoa

O corpo do pedido aceita estes campos para cada destinatário. A [introdução à API](https://knowledge.flowella.io/pt/api-reference/introduction.md) e o [documento OpenAPI](https://api.flowella.io/v1/openapi.json) descrevem o pedido completo.

| Campo | Para que serve |
| - | - |
| `phone` | O número WhatsApp da pessoa. Obrigatório. |
| `bodyParameters` | Valores para as variáveis do corpo, por ordem. Até 20. |
| `buttonParameters` | Valores para variáveis de botões de URL (`subType` `url`), botões de Flow (`subType` `flow`) ou botões de copiar código (`subType` `copy_code`). |

Para um modelo com cabeçalho de imagem, vídeo ou documento, pode definir uma ligação pública para o ficheiro em `headerMedia.url`, no nível superior do corpo.

### Envios repetidos e idempotência

`POST /v1/templates/send` protege-o de enviar a mesma mensagem duas vezes, o que é importante porque o Customer.io repete uma ação de webhook quando não recebe uma resposta `2xx`:

* Sem um cabeçalho `Idempotency-Key`, o Flowella usa um hash do corpo do pedido como chave. Um corpo idêntico byte a byte no prazo de 7 dias devolve o `id` original e não envia nada. Como o corpo de cada pessoa contém o seu próprio número, uma campanha normal envia uma vez para todos.
* Com um cabeçalho `Idempotency-Key`, qualquer pedido com a mesma chave no prazo de 7 dias devolve o `id` original e não envia nada, mesmo que o corpo tenha mudado.
* Além disso, o Flowella ignora um segundo envio do mesmo modelo para o mesmo número no prazo de 15 segundos.

> [!WARNING]
>
> Nunca deixe um valor fixo de `Idempotency-Key` numa ação de campanha ativa. Só a primeira pessoa recebe a mensagem: todos os pedidos seguintes reutilizam a chave, por isso o Flowella devolve o primeiro `id` e não envia nada. Remova o cabeçalho antes de iniciar a campanha, ou construa um valor diferente para cada pessoa, como o nome da campanha seguido de `{{customer.id}}`.

As mesmas regras explicam a maioria dos testes falhados. Enviar novamente o mesmo modelo à mesma pessoa de teste produz o mesmo corpo, por isso o Flowella não envia nada, a menos que altere o valor de `Idempotency-Key` de cada vez.

### Enviar para um segmento grande

Cada pedido do Customer.io coloca um envio em fila, e o Flowella entrega-o em segundo plano, repetindo em caso de erros temporários do WhatsApp. Aplicam-se dois limites a campanhas grandes:

* **O limite de mensagens da Meta.** A Meta limita o número de pessoas a quem pode enviar mensagens fora da janela de 24 horas num período móvel de 24 horas. Consulte [Limites de mensagens](https://knowledge.flowella.io/pt/whatsapp/limits/messaging-limits.md).
* **O limite de taxa da sua chave de API.** Os pedidos acima do limite devolvem `429` com um cabeçalho `Retry-After`. Consulte [Limites de taxa](https://knowledge.flowella.io/pt/api-reference/introduction.md#rate-limits).

Distribua os envios grandes com os controlos de envio do próprio Customer.io e acompanhe o progresso no separador **Statistics** do modelo. O Flowella ignora quem tiver feito opt-out no número a partir do qual envia. Consulte [Opt-outs](https://knowledge.flowella.io/pt/app/opt-outs.md).

## Sincronizar mensagens WhatsApp recebidas com o Customer.io (opcional)

Esta parte envia para o Customer.io cada mensagem WhatsApp que um contacto lhe envia, para que possa atualizar a pessoa ou iniciar outras campanhas a partir dela.

**1. Criar uma automação acionada por webhook no Customer.io**

Crie uma campanha ou automação acionada por webhook e copie o URL de webhook que o Customer.io gera. Consulte o guia do Customer.io sobre [campanhas de webhook](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**2. Adicionar um webhook de saída no Flowella**

No Flowella, aceda a **Settings** e depois **Webhooks**, e selecione **Add webhook**. Cole o URL do Customer.io em **Endpoint URL**, introduza um segredo de assinatura e assinale apenas `message.received` em **Events**. Consulte [Webhooks](https://knowledge.flowella.io/pt/settings/webhooks.md).

**3. Enviar dados de exemplo**

Envie a si próprio um modelo WhatsApp a partir do Flowella e responda-lhe, para que o Customer.io receba um evento `message.received` real a partir do qual pode construir o fluxo de trabalho. Cada evento tem este aspeto:

```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** no Flowella envia um evento `webhook.test`, que não tem contacto, por isso filtre-o no passo seguinte.

**4. Manter apenas as mensagens recebidas reais**

Adicione um **True/False Branch** que só continua quando o `type` do acionador é `message.received`.

**5. Procurar o contacto no Flowella**

O evento contém IDs, não o número de telefone. Adicione uma ação **Send and receive data** com o método `GET`, o URL `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}` e o mesmo cabeçalho `Authorization` de antes. A resposta inclui o `id`, `phone`, `waId`, `name`, `email`, `externalId`, `isOptedOut`, `createdAt` e `updatedAt` do contacto.

Para guardar a própria mensagem, adicione outro pedido a `GET /v1/messages/{{trigger.data.messageId}}`. O campo `body` contém o texto da mensagem e pode estar vazio.

**6. Atualizar a pessoa**

Adicione uma ação **Create or Update Person**. Escolha o identificador que o seu espaço de trabalho usa para pessoas e defina apenas os atributos de que precisa, como a hora da última resposta WhatsApp. Consulte o guia do Customer.io sobre [Create or update person](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> Numa automação acionada por webhook, **Create or Update Person** cria uma nova pessoa quando ninguém corresponde ao identificador. Para evitar criar pessoas que não pretende, adicione uma condição à ação para que o passo só seja executado quando o valor do identificador estiver presente, e teste com um número que não esteja no seu espaço de trabalho.

### Segurança do webhook de entrada

O Flowella assina todos os pedidos com o cabeçalho `X-Flowella-Signature`. Uma automação acionada por webhook no Customer.io não consegue verificar essa assinatura, por isso qualquer pessoa que tenha o URL de webhook do Customer.io pode publicar dados nele. Mantenha o URL privado e não use a sincronização de entrada para alterar atributos de consentimento ou de faturação. Consulte [Verificar assinaturas](https://knowledge.flowella.io/pt/api-reference/webhooks.md#verify-signatures) se encaminhar primeiro os eventos através do seu próprio endpoint.

### Opt-outs

Quando um contacto envia `STOP` ou outra palavra-chave de opt-out, o Flowella regista o opt-out nesse número WhatsApp e bloqueia todos os envios seguintes para esse contacto a partir desse número, incluindo os envios a partir do Customer.io. Consulte [Opt-outs](https://knowledge.flowella.io/pt/app/opt-outs.md).

Para copiar os opt-outs para o Customer.io, não dependa do evento `optout.created`: de momento, não é disparado no primeiro opt-out de um contacto num número. Em vez disso, liste os opt-outs com `GET /v1/opt-outs`, que aceita os filtros `createdAfter` e `phone`.

## Resolução de problemas

| Sintoma | Causa | Solução |
| - | - | - |
| `401` com `Invalid or expired API key` | A chave foi revogada ou substituída, ou foi colada incorretamente. | Crie uma nova chave e atualize o cabeçalho `Authorization`. Consulte [Chaves de API](https://knowledge.flowella.io/pt/settings/api-keys.md). |
| **Could not load API keys** no Flowella | Apenas Owners e Admins podem gerir chaves de API. | Peça a um Owner ou Admin que crie a chave. |
| `401` com `Missing bearer token` | O pedido foi para `https://app.flowella.io/api/v1`, que redireciona, e o cabeçalho perdeu-se. | Use `https://api.flowella.io/v1`. |
| Um teste devolve `202` mas nada chega | O corpo ou a `Idempotency-Key` corresponderam a um envio anterior nos últimos 7 dias, ou o mesmo modelo foi para o mesmo número nos últimos 15 segundos. | Use um novo valor de `Idempotency-Key` em cada teste. |
| Só a primeira pessoa da campanha recebeu a mensagem | Ficou um valor fixo de `Idempotency-Key` na ação. | Remova o cabeçalho ou torne o seu valor único para cada pessoa. |
| O envio mostra uma falha no separador **Statistics** | A Meta não conseguiu entregar a mensagem, por exemplo porque o número não está no WhatsApp. | Leia o motivo na coluna **Details**. Consulte [Códigos de erro da Meta](https://knowledge.flowella.io/pt/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** no separador **Statistics** | O atributo de telefone está vazio ou não está em formato internacional. | Guarde os números com o indicativo do país, como `+447700900123`. |
| O Customer.io não recebe eventos de entrada | O webhook do Flowella está inativo ou `message.received` não está assinalado. | Verifique o **Delivery log** do webhook no Flowella. Consulte [Webhooks](https://knowledge.flowella.io/pt/settings/webhooks.md#delivery-log). |

## Relacionado

> [card] [Introdução à API](https://knowledge.flowella.io/pt/api-reference/introduction.md)
>
> Autenticação, idempotência, limites de taxa e erros.

> [card] [Referência de webhooks](https://knowledge.flowella.io/pt/api-reference/webhooks.md)
>
> Tipos de eventos, corpos de pedido e assinaturas.

> [card] [Variáveis de modelos](https://knowledge.flowella.io/pt/app/template-variables.md)
>
> Variáveis, exemplos e valores de recurso.

> [card] [Envio em massa](https://knowledge.flowella.io/pt/app/bulk-send.md)
>
> Em alternativa, envie um modelo para uma lista a partir da aplicação Flowella.


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