CoralineGuias · 3.0

03 · IMPLANTAÇÃO

Conecte os canais com confiança.

O caminho completo para contratar, configurar e validar WhatsApp, SMS e e-mail no Coraline. Cada etapa aponta para a documentação oficial do provedor.

Revisado em 15 de agosto de 2026
Contrate o produto certo

Twilio Programmable Messaging e Twilio SendGrid Email API são transportes distintos.

Separe acesso e segredo

Use privilégios mínimos, cofre do ambiente e chaves independentes para operação e setup.

Assine toda entrada

O Coraline rejeita webhooks sem assinatura válida antes de interpretar o conteúdo.

00 · BASE COMUM

Comece pela origem pública.

Configure primeiro a origem canônica. Ela precisa ser pública, usar HTTPS e coincidir exatamente com o host recebido pelos provedores; qualquer redirect ou troca de protocolo invalida a assinatura.

APP_PUBLIC_ORIGINhttps://coraline-v3.higgsfield.app
01 · WhatsApp · SMS

Twilio

Crie a conta, habilite cobrança, reúna os remetentes em um Messaging Service e conecte os webhooks assinados do Coraline.

Criar conta Documentação oficial

  1. Abra a conta e prepare a cobrança

    O trial serve para descoberta, mas restringe destinos e recursos. Para produção, faça o upgrade pay as you go, habilite alertas e revise as permissões geográficas.

    • Confirme e-mail, telefone e os dados do projeto.
    • No Console, use Upgrade account e cadastre a forma de pagamento.
    • Mantenha habilitados somente os países realmente atendidos.
    Conta e upgrade

  2. Crie o Messaging Service e o número SMS

    Em Messaging > Services, crie o serviço Coraline 3.0. Compre um número com capacidade SMS compatível com os destinos e adicione-o ao Sender Pool.

    • Copie o SID MG do serviço para o ambiente do Coraline.
    • Use o webhook comum do serviço para mensagens recebidas, sempre por POST.
    • Valide opt-in, opt-out e regras regulatórias de cada país antes do envio.
    Configurar Messaging Service

  3. Teste e registre o WhatsApp

    Use o Sandbox apenas para descoberta. Para produção, a conta deve estar paga e o número precisa ser registrado por Self Sign-up com acesso administrativo ao Meta Business Portfolio.

    • No Sandbox, cada testador precisa enviar o código join antes de conversar.
    • Na produção, valide o número por OTP e conclua a verificação empresarial da Meta.
    • Associe o WhatsApp Sender ao mesmo Messaging Service do Coraline.
    Registrar WhatsApp Sender

  4. Aprove os templates fora da janela

    A resposta livre vale durante a janela de 24 horas iniciada pelo usuário. Fora dela, crie um Content Template, envie para aprovação e permita o respectivo SID HX no Coraline.

    • Escolha idioma e categoria compatíveis com o conteúdo real.
    • Forneça amostras para todas as variáveis do template.
    • Liste apenas SIDs aprovados em TWILIO_WHATSAPP_TEMPLATE_SIDS.
    Criar Content Template

  5. Crie credenciais de produção

    Prefira API Key revogável para a REST API. O Account SID e o Auth Token também permanecem configurados porque o Coraline valida assinaturas e busca anexos privados com eles.

    • Use Restricted API Key com a permissão mínima de criar mensagens quando disponível.
    • Guarde o secret exibido uma única vez diretamente no cofre do ambiente.
    • Nunca salve tokens em arquivos versionados ou no navegador.
    Gerenciar API Keys

  6. Conecte webhooks e valide o fluxo

    Configure a URL de entrada no serviço e mantenha a origem pública exatamente igual à usada pela Twilio. O status de cada envio já leva um callback com os identificadores internos.

    • Entrada: /api/webhooks/twilio/inbound por POST.
    • Status: /api/webhooks/twilio/status por POST.
    • Teste envio, resposta, opt-out, mídia e atualização de entrega no inbox.
    Segurança dos webhooks

Segredos e configuração

TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKENTWILIO_API_KEY_SIDTWILIO_API_KEY_SECRETTWILIO_MESSAGING_SERVICE_SIDTWILIO_WHATSAPP_TEMPLATE_SIDS

Webhooks do Coraline

Entrada Twilio · POST/api/webhooks/twilio/inbound
Status Twilio · POST/api/webhooks/twilio/status
02 · E-mail

Twilio SendGrid

Assine o Email API, autentique o domínio, crie uma chave mínima e conecte os webhooks de eventos e recebimento com assinatura ECDSA.

Criar conta Documentação oficial

  1. Assine o produto Email API

    O Coraline envia pela API v3 do SendGrid. Escolha Email API, não Marketing Campaigns e não o produto Twilio Email. Selecione o plano pelo volume e pelos recursos necessários.

    • Confirme a conta, habilite 2FA e conclua eventual revisão de compliance.
    • Em Account Details > Your Products, escolha o plano de Email API.
    • Consulte a tabela oficial antes de contratar; limites e preços podem mudar.
    Planos do Email API

  2. Autentique o domínio remetente

    Em Sender Authentication, inicie Domain Authentication e publique exatamente os registros DNS apresentados. Depois, use um endereço desse domínio como remetente do Coraline.

    • Mantenha Automated Security ligada no fluxo de envio.
    • Aguarde a propagação e clique em Verify no painel.
    • Evite Gmail, Yahoo e outros domínios públicos como remetente de produção.
    Autenticar domínio

  3. Crie a chave mínima de envio

    Crie uma API Key Custom Access chamada coraline-prod-mail-send. Conceda Full Access somente a Mail Send e deixe as demais áreas sem acesso.

    • Copie a chave no momento da criação; ela não será exibida novamente.
    • Configure a chave e o endereço From apenas no ambiente de produção.
    • Use outra chave temporária para tarefas administrativas e revogue-a depois.
    Criar API Key

  4. Ative o Event Webhook assinado

    Em Mail Settings > Event Webhooks, crie um webhook para o endpoint de eventos. Selecione os estados operacionais, ative Signed Event Webhook e salve antes de testar.

    • Inclua processed, delivered, bounced, dropped, spam report e unsubscribe.
    • Reabra o webhook e copie a public verification key gerada.
    • Configure a chave pública no Coraline antes de usar Test Integration.
    Assinar Event Webhook

  5. Configure o Inbound Parse

    Reserve um subdomínio exclusivo, aponte seu MX com prioridade 10 para mx.sendgrid.net e conecte o destino ao endpoint de entrada do Coraline.

    • Não troque o MX do domínio corporativo principal.
    • Deixe POST the raw, full MIME message desmarcado; o Coraline usa multipart.
    • O endereço local pode variar, exceto abuse, postmaster e unsubscribe.
    Configurar Inbound Parse

  6. Assine a entrada e teste ponta a ponta

    Crie uma webhook security policy com assinatura, associe-a ao Parse Setting e guarde a chave pública retornada. O Coraline valida os bytes brutos antes de interpretar o e-mail.

    • Teste um envio e aguarde o evento delivered; HTTP 202 significa apenas aceito.
    • Envie uma resposta ao subdomínio de entrada e confirme a conversa no inbox.
    • Repita com um anexo pequeno e verifique os logs em caso de HTTP 403.
    Assinar Inbound Parse

Segredos e configuração

SENDGRID_API_KEYSENDGRID_FROM_EMAILSENDGRID_EVENT_WEBHOOK_PUBLIC_KEYSENDGRID_INBOUND_WEBHOOK_PUBLIC_KEY

Webhooks do Coraline

Eventos SendGrid · POST/api/webhooks/sendgrid/events
Entrada SendGrid · POST/api/webhooks/sendgrid/inbound

03 · ANTES DE ABRIR

Teste o ciclo inteiro.

  • Contas pagas ou trials compatíveis com o teste planejado.
  • Remetentes, domínios, consentimentos e requisitos regulatórios aprovados.
  • Segredos configurados no ambiente, nunca em arquivos versionados.
  • APP_PUBLIC_ORIGIN igual à origem pública HTTPS, sem barra final.
  • Webhooks por POST, sem redirects, com as chaves de assinatura correspondentes.
  • Envio, resposta, status, opt-out e anexo validados em cada canal usado.