Pular para o conteúdo principal

Transporte pelo Joinotify Cloud

O plugin entrega as mensagens por um canal. Existem dois canais de WhatsApp, e eles convivem no mesmo site:

CanalComo conectaTipos de mensagem
WhatsApp (Cloud API)token do Joinotify Cloudtexto, mídia, áudio e template
WhatsApp (Evolution)QR Code, pelo relay antigotexto, mídia e áudio

O canal do Cloud fala com a API do Joinotify Cloud — a mesma que qualquer integração externa usa — e por trás dela está a Cloud API oficial da Meta. É o caminho recomendado: o número é oficial, o envio é assinado pela Meta e não depende de uma sessão de WhatsApp Web viva no servidor.

Configurando​

Vá em Joinotify → Configurações → Geral, no card WhatsApp Cloud API.

CampoO que faz
Transporte de mensagensAutomático, Cloud API (oficial) ou Evolution (legado)
Token da APIo token do Joinotify Cloud (sk_live_…)
ID do número de telefoneo phone_number_id usado como origem
ID da conta empresarialo waba_id dono dos templates

No modo Automático — o padrão — o plugin usa a Cloud API sempre que houver um token disponível e cai para o Evolution quando não houver. Os outros dois valores forçam um transporte específico, útil para testar ou para segurar a migração.

Você provavelmente não precisa preencher nada

Quando sua licença já tem um número do Joinotify Cloud provisionado, o token, o phone_number_id e o waba_id chegam junto com a licença. Os campos acima são sobrescritas manuais: preencha só para apontar o site para outro número ou outra conta. Em branco, vale o que veio da licença.

Onde encontrar cada identificador no painel do Joinotify Cloud está descrito em Início rápido.

A janela de 24 horas muda o que você pode enviar​

Essa é a diferença que mais aparece no dia a dia. No relay antigo, texto livre saía a qualquer momento. Na Cloud API oficial, fora da janela de 24 horas desde a última mensagem do cliente, só um template aprovado é entregue — texto livre é recusado pela Meta.

Na prática:

  • Fluxos que respondem a uma conversa em andamento continuam funcionando igual.
  • Fluxos que iniciam a conversa — "seu pedido saiu para entrega", "avalie sua compra depois de 7 dias" — caem fora da janela e precisam de template.

O conceito completo, com as categorias de template e o custo de cada uma, está em A janela de 24 horas e em Templates.

Ainda não há uma ação "Enviar template" no construtor

O construtor oferece WhatsApp: mensagem de texto e WhatsApp: mensagem de mídia. O envio de template existe no canal, mas ainda não como um nó do fluxo — por enquanto ele é alcançável por código (veja abaixo) ou direto pela API do Cloud.

Enviando um template por código​

O envio passa pela camada de notificações, que resolve o canal ativo:

functions.php ou um plugin próprio
$resultado = joinotify_dispatch_notification( array(
    'channel'  => 'whatsapp_cloud',
    'type'     => 'template',
    'sender'   => joinotify_get_first_sender(),
    'receiver' => '5541987111527',
    'meta'     => array(
        'template_name' => 'pedido_enviado',
        'language'      => 'pt_BR',
        'components'    => array(
            array(
                'type'       => 'body',
                'parameters' => array(
                    array( 'type' => 'text', 'text' => '1042' ),
                ),
            ),
        ),
    ),
) );

if ( ! $resultado->is_success() ) {
    error_log( 'Falha ao enviar o template: ' . $resultado->error );
}

O formato de components é o mesmo da API — veja Enviar mensagens.

Como o plugin escolhe o número de origem​

O phone_number_id é resolvido a partir do remetente do fluxo. Quando o número não tem um phone_number_id próprio mapeado, vale o padrão da conta — o campo ID do número de telefone das configurações, ou o valor provisionado com a licença.

Erros e reenvio​

Uma falha de envio não é descartada: a mensagem vai para a fila de processamento (Joinotify → Fila de processamento) e é reenviada. Erros de configuração — token inválido, template inexistente, janela fechada — não são reenviados, porque insistir não muda o resultado; eles ficam registrados no histórico e nos logs.

O erro mais comum em produção é a janela fechada, registrado como window_closed_requires_template. A tabela completa de códigos está em Erros.

Apontando para outro ambiente​

Para testes contra um ambiente que não seja o de produção, defina a constante no wp-config.php:

wp-config.php
define( 'JOINOTIFY_CLOUD_API_BASE_URL', 'https://api.exemplo.com' );

Sem a constante, o plugin fala com https://api.joinotify.com.