O bloco de gatilho de API inicia um cenário de automação quando dados são recebidos de uma fonte externa — o seu site, aplicativo, CRM ou plataformas como o Shopify.
Os dados recebidos podem ser usados para personalizar os e-mails com conteúdo dinâmico baseado em ações do cliente ou contato. Dependendo da sua configuração, é possível usar o bloco de gatilho de API para enviar campanhas automáticas do tipo “drip”, e-mails transacionais ou recomendações personalizadas.
Configurar o bloco de gatilho de API
Para começar a enviar campanhas automáticas com conteúdo dinâmico, crie um cenário com o bloco de gatilho de API no editor de automação omnichannel e configure a integração com a fonte externa.
Criar novo cenário
Acesse Cenários e crie um novo cenário. Selecione a aba Gatilhos no painel na parte inferior do construtor de cenários e arraste o bloco de gatilho de API para a área de trabalho.
Depois, construa o restante do cenário usando os blocos disponíveis e adicionando os modelos de e-mail para criar uma sequência de e-mails.
Por exemplo, você pode configurar uma sequência de boas-vindas para novos contatos.
Primeiro, o cenário envia um e‑mail de boas‑vindas. Depois de três dias, um e‑mail de acompanhamento com desconto é enviado aos contatos que não clicaram no link da loja.
Quando tudo estiver configurado, execute o cenário — caso contrário, os dados recebidos via API não serão processados.
Configurar integração com fonte externa
Para configurar a integração com uma fonte externa como um site, aplicativo, Webflow ou Shopify, você vai precisar de um desenvolvedor. Ele configurará a integração da API para enviar requisições POST para o URL(1) gerado pelo bloco de gatilho de API.
Os dados enviados nas requisições devem estar no formato JSON.
No mínimo, cada requisição deve incluir um endereço de e‑mail ou número de telefone (2), pois a Selzy usa essas informações para identificar os destinatários. Você também pode incluir mais dados relevantes para o seu cenário, como: nome do cliente, código promocional, lista de produtos ou serviços, total do pedido, etc.
Exemplo de requisição:
POST https://api.selzy.com/en/api/triggerBlock/{blockId}
Content-Type: application/json
{
"email": "hello@example.com",
"products": [
{
"name": "Coffee mug",
"link": "https://example.com/link1"
},
{
"name": "Coaster",
"link": "https://example.com/link2"
}
]
}
Respostas do servidor
Se a requisição for enviada com sucesso, você receberá a seguinte resposta:
{
"success": true
}
Se a requisição não incluir endereço de e‑mail nem número de telefone, o servidor retornará o seguinte erro:
{
"error": "Error ID:... Can't define contact",
"code": "invalid_arg"
}
Se o URL do gatilho de API contiver um ID incorreto do bloco de gatilho de API, o servidor retornará o seguinte erro:
{
"error": "Error ID:... Invalid UUID string",
"code": "invalid_arg"
}
Usar dados JSON recebidos em campanhas de e‑mail
Os dados JSON recebidos de uma fonte externa não apenas acionam o cenário, como também permitem personalizar os e‑mails. Por exemplo, você pode tratar seus clientes pelo nome, listar os produtos pedidos ou incluir uma data de entrega.
Para personalizar e‑mails, processe os dados JSON recebidos usando Liquid, uma linguagem de template criada pelo Shopify, e depois insira o código Liquid no construtor de e‑mails da Selzy. Tanto a linha de assunto quanto o corpo do e‑mail suportam conteúdo dinâmico.
Processar dados JSON usando Liquid
Para exibir conteúdo dinâmico nos seus e‑mails, o código Liquid deve referenciar variáveis das requisições de API recebidas.
Se quiser personalizar ainda mais o conteúdo dinâmico, você pode usar filtros e tags que controlam como os dados recebidos aparecem.
Variáveis
As variáveis são incluídas nas requisições de API recebidas e seu formato depende inteiramente da configuração da sua fonte externa.
Para exibir os dados recebidos no seu e‑mail, envolva as variáveis com chaves duplas: {{variável}}. Certifique‑se de especificar uma única chave do bloco de gatilho de API antes da variável. Isso informa ao sistema onde encontrar os dados para o seu e‑mail.
Você pode editar a chave nas configurações do bloco de gatilho de API. No entanto, se alterar a chave, garanta que o seu código Liquid seja atualizado com a nova chave; caso contrário, os dados recebidos não aparecerão no e‑mail.
| Exemplo de requisição de API (JSON) | Código Liquid no conteúdo do e‑mail | Resultado final do e‑mail |
| {
"email": "hello@example.com", "name": "Ursula" } |
Hello {{ ApiTrigger1.name }}!
Your email: {{ ApiTrigger1.email }} |
Hello Ursula!
Your email: hello@example.com |
| Bloco de gatilho de API | Construtor de e‑mails da Selzy (Modo Código) | Visualização na caixa de entrada do destinatário |
Filtros
Os filtros permitem formatação e personalização do conteúdo dinâmico. Por exemplo, o filtro ‘capitalize’ converte “helena” em “Helena” se o nome estiver originalmente em minúsculas. Filtros são aplicados depois das variáveis e são separados por uma barra vertical ( | ).
| Filtro | Exemplo de requisição de API (JSON) | Código Liquid no conteúdo do e‑mail | Resultado final do e‑mail |
| capitalize — Converte texto para Título | { "name": "helena" } | Olá {{ ApiTrigger1.name | capitalize }}! | Olá Helena! |
| upcase — Converte texto para LETRA MAIÚSCULA | { "promocode": "verao2025" } | Consiga o seu cupom de desconto: {{ ApiTrigger1.promo | upcase }} | Consiga o seu cupom de desconto: VERAO2025 |
| downcase — Converte o texto para minúsculas | { "promocode": "VERAO2025" } | Consiga o seu cupom de desconto:{{ ApiTrigger1.promo | downcase }} | Consiga o seu cupom de desconto: verao20252025 |
| replace —
Encontra e substitui todas as ocorrências de um texto específico em uma linha |
{
"social_link": "https://twitter.com/example_user" } |
<a href="{{ social_link | replace: 'twitter.com', 'x.com' }}">
Follow us on {{ "Twitter" | replace: "Twitter", "X" }}! </a> |
Siga-nos no X! |
| default — Fornece um valor de alternativa se a variável estiver vazia | { "name": "" } | Olá {{ ApiTrigger1.name | default: ", querido cliente" }}! | Olá, querido cliente! |
| date — Formata uma data em um formato específico | { "delivery_date": "01-05-2025" } | Data de entrega: {{ ApiTrigger1.delivery_date | date: "%-d de %B, %Y" }} | Data de entrega: 1 de Maio, 2025 |
Você pode combinar vários filtros para modificar uma variável em uma única etapa. Os filtros são aplicados em ordem, da esquerda para a direita, o que significa que cada filtro modifica o resultado do anterior.
| Exemplo de requisição de API (JSON) | Código Liquid no conteúdo do e‑mail | Resultado final do e‑mail |
| { "delivery_date": "2025-05-01" } | Data de entrega: {{ ApiTrigger1.delivery_date | date: "%-d de %B, %Y" | upcase }} | Data de entrega: 1 DE MAIO, 2025 |
Tags
As tags controlam o conteúdo dinâmico que os destinatários veem.
Para a maioria das comunicações relacionadas ao carrinho do cliente, você vai precisar das tags ‘for’ e ‘if’.
for
A tag ‘for’ é geralmente usada para mostrar itens de carrinho abandonado, compras recentes ou produtos recomendados em e‑mails.
| Exemplo de requisição de API (JSON) | Código Liquid no conteúdo do e‑mail | Resultado final do e‑mail |
| {
"customer": { "email": "helena@exemplo.com", "cart": [ { "name": "Fone de ouvido sem fio", "price": 140.00, "link": "https://example.com/products/wireless-headphones" }, { "name": "Relógio inteligente", "price": 125.00, "link": "https://example.com/products/smartwatch" } ] } } |
<p>Olá {{ ApiTrigger1.customer.email }},</p>
<p>O que ficou para trás no seu carrinho:</p> <ul> {% for item in ApiTrigger1.customer.cart %} <li>{{ item.name }} - R${{ item.price }} - <a href="{{ item.link }}">Ver item</a></li> {% endfor %} </ul> |
Olá helena@exemplo.com,
O que ficou para trás no seu carrinho: - Fone de ouvido sem fio - R$140.00 - Ver Item - Relógio inteligente - R$125.00 - Ver Item |
if
A tag ‘if’ controla o conteúdo dinâmico com base em condições especificadas. Ela é frequentemente usada para ofertas personalizadas, como descontos para assinantes, frete grátis ou brindes para pedidos acima de um determinado valor.
A tag ‘if’ é frequentemente usada com operadores de comparação (==, !=, >, <, >=, <=) e lógicos (or, and, contains).
| Exemplo de requisição de API (JSON) | Código Liquid no conteúdo do e‑mail | Resultado final do e‑mail |
| {
"customer": { "email": "helena@exemplo.com", "cart_total": 65.00, "cart": [ { "name": "Fone de ouvido sem fio", "price": 140.00, "link": "https://exemplo.com/produtos/fone-semfio" }, { "name": "Relógio inteligente", "price": 125.00, "link": "https://exemplo.com/produtos/relogio-inteligente" } ] } } |
<p>Hey {{ ApiTrigger1.customer.email }},</p>
{% if ApiTrigger1.customer.cart_total >= 50 %} <p>Boas notícias! O seu pedido se qualifica a <strong>entrega GRÁTIS</strong>.</p> {% else %} <p>Adicione mais itens ao seu carrinho para desbloquear <strong>entrega GRÁTIS</strong> em pedidos acima de R$100!</p> {% endif %} <p>O que ficou para trás no seu carrinho:</p> <ul> {% for item in ApiTrigger1.customer.cart %} <li>{{ item.name }} - R${{ item.price }} - <a href="{{ item.link }}"> Ver Item</a></li> {% endfor %} </ul> |
Olá helena@exemplo.com,
Ótimas notícias! O seu pedido se qualifica a entrega GRÁTIS. O que ficou para trás no seu carrinho: - Fone de ouvido sem fio - R$140.00 - Ver Item - Relógio inteligente - R$125.00 - Ver Item |
Para saber mais sobre Liquid, consulte a documentação do usuário. Também recomendamos testar o playground deles para experimentar a formatação de conteúdo dinâmico e validar códigos específicos do seu cenário.
Inserir código Liquid no conteúdo do e‑mail
Para usar os dados JSON recebidos, passe o mouse sobre a prévia do e‑mail no bloco de Email do seu cenário e clique em Editar.
Quando o construtor de e‑mails abrir, mude para o Modo de Código.
Insira o código Liquid no local correto do código do e‑mail. Certifique‑se de referenciar a chave única do bloco de gatilho de API; caso contrário, os dados recebidos não aparecerão no e‑mail.
Testar cenário com gatilho de API
Você pode testar cenários com o bloco de gatilho de API simulando requisições de API usando o Postman ou ferramentas similares de teste de API. Assim, você pode validar seu cenário e pré‑visualizar a campanha de e‑mail como os contatos veriam — sem precisar de dados reais.
Para começar os testes, crie uma nova requisição POST no Postman. Copie o URL de POST do bloco de gatilho de API e cole no campo da requisição. Certifique‑se de definir o formato da requisição como JSON.
Adicione um corpo JSON com as variáveis necessárias para o gatilho de API. Para o endereço de e‑mail, use um ao qual você tenha acesso para poder visualizar a campanha. Envie a requisição para testar como o cenário responde.
Se o cenário funcionar corretamente, você receberá um e‑mail no endereço incluído na requisição.
Erros
Se um cenário de automação com um bloco de gatilho de API não funcionar corretamente ou se os dados recebidos não aparecerem nos e‑mails, comece identificando onde ocorreu o erro. Se foi no lado da fonte externa, no Liquid ou na Selzy.
Abaixo, você encontrará uma lista de erros comuns e possíveis soluções:
- Erros de integração. Se um cenário na Selzy não receber dados ou os receber com erros, verifique a integração no lado da fonte externa e garanta que:
- O URL correto do bloco de gatilho de API está sendo usado.
- A requisição POST contém um endereço de e‑mail ou número de telefone.
- Os dados são enviados em formato JSON.
Observe que o bloco de gatilho de API não gera erros específicos no lado da Selzy, pois ele apenas recebe dados e inicia cenários. Se a configuração parecer correta, mas ainda não estiver funcionando, você provavelmente precisará de assistência do seu desenvolvedor ou da plataforma com a qual está integrando à Selzy.
- Erros de código Liquid. Se os dados recebidos não aparecerem nos e‑mails, verifique:
- As variáveis e a chave do bloco de gatilho de API estão referenciadas corretamente.
- Não há erros de digitação ou espaços desnecessários.
- O número de chaves está correto e os filtros foram aplicados adequadamente.
Você pode usar o Playground Liquid para testar se o seu código Liquid produz o resultado correto e consultar a documentação do usuário para identificar e corrigir problemas de formatação.
- Erros de cenário. Se um cenário na Selzy não receber dados ou não enviar e‑mails, verifique as configurações do cenário e certifique‑se de que ele está ativo.
Vá para a lista de seus cenários, encontre o cenário que não está funcionando corretamente e abra a página de estatísticas detalhadas. Lá você encontrará o status atual do cenário, métricas‑chave de desempenho e erros.
Se faltarem blocos ou conteúdo no cenário, é provável que você não tenha salvo as alterações mais recentes. Volte ao editor de cenários e atualize o cenário clicando em Atualizar e iniciar no topo da tela.
Se estiver com dificuldades para identificar ou corrigir erros do cenário, entre em contato com a equipe de suporte da Selzy para obter assistência.
