{ "api": "Zapcel API REST", "versao": "v1", "transporte": "WhatsApp Cloud API oficial (Meta)", "base_url": "https://zapcel.com.br/v1", "autenticacao": { "tipo": "Bearer", "cabecalho": "Authorization: Bearer SEU_TOKEN", "observacao": "Token da empresa, gerado em Configuracoes > API REST. Nas portas POST o token tambem pode ir no corpo (campo token)." }, "janela_24h": "texto, midia, botoes e menu so para quem escreveu na conexao nas ultimas 24 h; fora dela 422 janela_fechada e o caminho e o template", "portas": { "info": { "menu": { "grupo": "Conexão", "nome": "Info da Conexão", "metodo": "GET", "ativo": true, "resumo": "O que a conexão é e como ela está agora.", "caminho": "/v1/conexao/info" }, "detalhe": { "cabecalhos": [ [ "Authorization", "Bearer SEU_TOKEN" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": null, "consulta": { "conexao": "ID_DA_CONEXAO_OFICIAL" }, "campos": [ [ "conexao", "texto", true, "O identificador desta conexão, na consulta (?conexao=)." ] ], "respostas": [ { "codigo": "200", "titulo": "O estado da conexão", "tom": "ok", "nota": "opera diz se a conexão está de pé agora. webhook mostra o endereço gravado.", "json": { "conexao": "ID_DA_CONEXAO_OFICIAL", "nome": "Financeiro", "versao": "v1", "tipo": "oficial", "numero": "5581999999999", "estado": "conectada", "ativa": true, "opera": true, "janela_de_24h": true, "templates_aprovados": 12, "freio_de_ritmo": false, "webhook": { "url": "https://seusistema.com.br/zapcel", "ativo": true } } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ] ], "notas": [ { "tom": "t", "icone": "M7 11V8a5 5 0 0 1 10 0v3M5 11h14v10H5z", "titulo": "O token vai no cabeçalho", "texto": "Esta porta é GET, e o token vai em Authorization: Bearer. Na consulta ele entraria em texto puro no registro de acesso do servidor." } ] } }, "webhook": { "menu": { "grupo": "Conexão", "nome": "Webhook", "metodo": "POST", "ativo": true, "resumo": "Para onde o Zapcel avisa quando algo acontece na conexão.", "caminho": "/v1/conexao/webhook" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "url": "https://seusistema.com.br/zapcel/webhook", "ativo": true }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "url", "texto", true, "O endereço https que recebe os eventos. Mande null para remover o webhook." ], [ "ativo", "booleano", false, "Liga ou desliga o envio sem apagar o endereço. O padrão é true." ] ], "respostas": [ { "codigo": "200", "titulo": "O webhook gravado", "tom": "ok", "nota": "O segredo da assinatura não viaja aqui: ele é lido nesta tela, em Webhook.", "json": { "url": "https://seusistema.com.br/zapcel/webhook", "ativo": true, "eventos": [ "mensagem.recebida", "mensagem.status", "conexao.status" ], "assinatura": { "cabecalho": "X-Zapcel-Assinatura", "algoritmo": "HMAC-SHA256 do corpo, em hexadecimal, com o prefixo sha256=", "segredo_gerado": true } } }, { "codigo": "evento", "titulo": "O que chega no seu endereço", "tom": "ok", "nota": "Um POST com este corpo e os cabeçalhos X-Zapcel-Assinatura, X-Zapcel-Evento, X-Zapcel-Entrega e X-Zapcel-Tentativa. Responda 2xx em até 10 segundos.", "json": { "id": "0b9d1c0e-7a3c-4f6e-9d57-4d2f3b0a1c11", "evento": "mensagem.recebida", "criado_em": "2026-10-14T15:04:05-03:00", "conexao": "ID_DA_CONEXAO_OFICIAL", "dados": { "id": "8841", "de": "5581999999999", "tipo": "texto", "texto": "Oi, quero a segunda via", "midia": null, "recebida_em": "2026-10-14T15:04:05-03:00" } } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "url_invalida", "O endereço não é https, tem usuário e senha, passa de 500 caracteres ou aponta para rede interna." ] ], "notas": [ { "tom": "t", "icone": "M10 13a5 5 0 0 0 7 0l2-2a5 5 0 0 0-7-7l-1 1M14 11a5 5 0 0 0-7 0l-2 2a5 5 0 0 0 7 7l1-1", "titulo": "Três eventos", "texto": "mensagem.recebida (o cliente escreveu), mensagem.status (aceita, entregue, lida ou falhou, com o mesmo id que a chamada de envio devolveu) e conexao.status (a conexão mudou de estado)." }, { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "Confira a assinatura e tente de novo", "texto": "Calcule o HMAC SHA-256 do corpo bruto com o segredo e compare com X-Zapcel-Assinatura. Se o seu endereço não responder 2xx, o Zapcel tenta mais duas vezes, depois de 1 minuto e de 5 minutos." }, { "tom": "t", "icone": "M4 5h16v14H4zM4 16l5-5 4 4 3-3 4 4M15 9h.01", "titulo": "Mídia recebida", "texto": "O evento traz o tipo, o mime e o nome do arquivo. O download do arquivo recebido ainda não está na API." } ] } }, "mensagem": { "menu": { "grupo": "Mensagens", "nome": "Enviar Mensagem", "metodo": "POST", "ativo": true, "resumo": "Manda um texto para um cliente que escreveu nas últimas 24 horas.", "caminho": "/v1/mensagens/mensagem" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "para": "5581999999999", "mensagem": "Olá! Sua fatura foi gerada." }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "para", "texto", true, "O telefone de destino, de 10 a 15 dígitos." ], [ "mensagem", "texto", true, "O texto, de até 4096 caracteres." ] ], "respostas": [ { "codigo": "202", "titulo": "Quando o canal aceita", "tom": "ok", "nota": "id é o identificador da mensagem: o webhook mensagem.status o repete quando ela for entregue, lida ou falhar. conversa só vem preenchida quando já existia uma conversa viva e a mensagem entrou nela; a API não abre conversa.", "json": { "status": "aceita", "id": "5b1f6a0e-93a2-4c7f-8f3e-6c9a2d0b7e21", "para": "5581999999999", "entregue_como": "texto", "conversa": null } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "janela_fechada", "O cliente não escreveu nesta conexão nas últimas 24 horas. Fora da janela só sai template (caminho: /v1/mensagens/template).", true ], [ "422", "numero_invalido", "O para não tem de 10 a 15 dígitos." ], [ "422", "numero_nao_tem_whatsapp", "O número não tem WhatsApp. Nada foi enviado.", true ], [ "422", "envio_recusado_pelo_canal", "A conexão não conseguiu enviar. O campo motivo traz a causa dela." ], [ "429", "limite_do_plano", "O limite de envios da API no mês foi atingido. O cabeçalho Retry-After diz em quantos segundos volta.", true ], [ "503", "limite_nao_conferido", "Não deu para conferir o limite do plano agora. Nada foi enviado; tente de novo." ] ], "notas": [ { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "A janela de 24 horas", "texto": "Na API oficial, texto, mídia, botões e menu só saem para quem escreveu nesta conexão nas últimas 24 horas. Fora dela a resposta é 422 janela_fechada, e o caminho é o template." } ] } }, "midia": { "menu": { "grupo": "Mensagens", "nome": "Enviar Mensagem com Mídia", "metodo": "POST", "ativo": true, "resumo": "Manda imagem, documento ou áudio.", "caminho": "/v1/mensagens/midia" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "para": "5581999999999", "tipo": "imagem", "midia": "https://seusistema.com.br/arquivos/fatura.png", "legenda": "Sua fatura" }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "para", "texto", true, "O telefone de destino, de 10 a 15 dígitos." ], [ "tipo", "texto", true, "imagem, documento ou audio. Vídeo não é aceito." ], [ "midia", "texto", true, "Um endereço https público ou o arquivo em base64 (com ou sem o prefixo data:)." ], [ "nome", "texto", false, "O nome do arquivo, para documento. A extensão deve bater com o conteúdo." ], [ "legenda", "texto", false, "O texto que acompanha imagem ou documento. Áudio não tem legenda." ] ], "respostas": [ { "codigo": "202", "titulo": "Quando o canal aceita", "tom": "ok", "nota": "id é o identificador da mensagem: o webhook mensagem.status o repete quando ela for entregue, lida ou falhar. conversa só vem preenchida quando já existia uma conversa viva e a mensagem entrou nela; a API não abre conversa.", "json": { "status": "aceita", "id": "5b1f6a0e-93a2-4c7f-8f3e-6c9a2d0b7e21", "para": "5581999999999", "entregue_como": "imagem", "conversa": null } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "janela_fechada", "O cliente não escreveu nesta conexão nas últimas 24 horas. Fora da janela só sai template (caminho: /v1/mensagens/template).", true ], [ "422", "numero_invalido", "O para não tem de 10 a 15 dígitos." ], [ "422", "numero_nao_tem_whatsapp", "O número não tem WhatsApp. Nada foi enviado.", true ], [ "422", "envio_recusado_pelo_canal", "A conexão não conseguiu enviar. O campo motivo traz a causa dela." ], [ "429", "limite_do_plano", "O limite de envios da API no mês foi atingido. O cabeçalho Retry-After diz em quantos segundos volta.", true ], [ "503", "limite_nao_conferido", "Não deu para conferir o limite do plano agora. Nada foi enviado; tente de novo." ], [ "422", "formato_nao_suportado", "Imagem: JPG ou PNG até 5 MB. Documento: PDF, Word, Excel, PowerPoint ou TXT até 16 MB. Áudio: OGG com Opus. O formato é lido do arquivo, e não do nome." ], [ "422", "midia_grande", "O arquivo passa do limite de tamanho do tipo." ], [ "422", "midia_invalida", "midia não é um endereço https nem um base64 válido." ], [ "422", "midia_inacessivel", "O Zapcel não conseguiu buscar o arquivo no endereço." ], [ "422", "url_invalida", "O endereço da mídia não é https ou aponta para rede interna." ] ], "notas": [ { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "A janela de 24 horas", "texto": "Na API oficial, texto, mídia, botões e menu só saem para quem escreveu nesta conexão nas últimas 24 horas. Fora dela a resposta é 422 janela_fechada, e o caminho é o template." }, { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "O endereço é buscado com travas", "texto": "Só https, só servidor público, sem redirecionamento e com teto de tamanho. Para mandar de um servidor interno, mande o arquivo em base64." } ] } }, "botoes": { "menu": { "grupo": "Mensagens", "nome": "Enviar Botões", "metodo": "POST", "ativo": true, "resumo": "Manda até 3 botões de resposta rápida.", "caminho": "/v1/mensagens/botoes" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "para": "5581999999999", "mensagem": "Posso confirmar a visita para amanhã?", "botoes": [ { "id": "sim", "titulo": "Sim" }, { "id": "nao", "titulo": "Não" } ] }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "para", "texto", true, "O telefone de destino, de 10 a 15 dígitos." ], [ "mensagem", "texto", true, "O texto que fica acima dos botões." ], [ "botoes", "lista", true, "De 1 a 3 botões, cada um com titulo (até 20 caracteres, sem repetir) e id (opcional)." ] ], "respostas": [ { "codigo": "202", "titulo": "Quando o canal aceita", "tom": "ok", "nota": "id é o identificador da mensagem: o webhook mensagem.status o repete quando ela for entregue, lida ou falhar. conversa só vem preenchida quando já existia uma conversa viva e a mensagem entrou nela; a API não abre conversa.", "json": { "status": "aceita", "id": "5b1f6a0e-93a2-4c7f-8f3e-6c9a2d0b7e21", "para": "5581999999999", "entregue_como": "botoes", "conversa": null } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "janela_fechada", "O cliente não escreveu nesta conexão nas últimas 24 horas. Fora da janela só sai template (caminho: /v1/mensagens/template).", true ], [ "422", "numero_invalido", "O para não tem de 10 a 15 dígitos." ], [ "422", "numero_nao_tem_whatsapp", "O número não tem WhatsApp. Nada foi enviado.", true ], [ "422", "envio_recusado_pelo_canal", "A conexão não conseguiu enviar. O campo motivo traz a causa dela." ], [ "429", "limite_do_plano", "O limite de envios da API no mês foi atingido. O cabeçalho Retry-After diz em quantos segundos volta.", true ], [ "503", "limite_nao_conferido", "Não deu para conferir o limite do plano agora. Nada foi enviado; tente de novo." ] ], "notas": [ { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "A janela de 24 horas", "texto": "Na API oficial, texto, mídia, botões e menu só saem para quem escreveu nesta conexão nas últimas 24 horas. Fora dela a resposta é 422 janela_fechada, e o caminho é o template." }, { "tom": "t", "icone": "M3 7h18v10H3zM7 12h4", "titulo": "Só na API oficial", "texto": "O QR Code não envia botões. Na v2 esta porta responde 422 canal_sem_interativo, e nada é enviado." } ] } }, "menu": { "menu": { "grupo": "Mensagens", "nome": "Enviar Menu", "metodo": "POST", "ativo": true, "resumo": "Manda uma lista de até 10 opções.", "caminho": "/v1/mensagens/menu" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "para": "5581999999999", "mensagem": "Escolha o seu plano", "botao": "Ver planos", "itens": [ { "id": "p100", "titulo": "100 Mega", "descricao": "R$ 79,90 por mês" }, { "id": "p300", "titulo": "300 Mega", "descricao": "R$ 99,90 por mês" } ] }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "para", "texto", true, "O telefone de destino, de 10 a 15 dígitos." ], [ "mensagem", "texto", true, "O texto que fica acima da lista." ], [ "botao", "texto", false, "O texto do botão que abre a lista, até 20 caracteres. O padrão é Ver opções." ], [ "itens", "lista", true, "De 1 a 10 itens, cada um com titulo (até 24 caracteres, sem repetir), id e descricao (até 72 caracteres), os dois opcionais." ] ], "respostas": [ { "codigo": "202", "titulo": "Quando o canal aceita", "tom": "ok", "nota": "id é o identificador da mensagem: o webhook mensagem.status o repete quando ela for entregue, lida ou falhar. conversa só vem preenchida quando já existia uma conversa viva e a mensagem entrou nela; a API não abre conversa.", "json": { "status": "aceita", "id": "5b1f6a0e-93a2-4c7f-8f3e-6c9a2d0b7e21", "para": "5581999999999", "entregue_como": "lista", "conversa": null } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "janela_fechada", "O cliente não escreveu nesta conexão nas últimas 24 horas. Fora da janela só sai template (caminho: /v1/mensagens/template).", true ], [ "422", "numero_invalido", "O para não tem de 10 a 15 dígitos." ], [ "422", "numero_nao_tem_whatsapp", "O número não tem WhatsApp. Nada foi enviado.", true ], [ "422", "envio_recusado_pelo_canal", "A conexão não conseguiu enviar. O campo motivo traz a causa dela." ], [ "429", "limite_do_plano", "O limite de envios da API no mês foi atingido. O cabeçalho Retry-After diz em quantos segundos volta.", true ], [ "503", "limite_nao_conferido", "Não deu para conferir o limite do plano agora. Nada foi enviado; tente de novo." ] ], "notas": [ { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "A janela de 24 horas", "texto": "Na API oficial, texto, mídia, botões e menu só saem para quem escreveu nesta conexão nas últimas 24 horas. Fora dela a resposta é 422 janela_fechada, e o caminho é o template." }, { "tom": "t", "icone": "M4 5h16v11H8l-4 4zM8 9h8M8 12h5", "titulo": "Só na API oficial", "texto": "O QR Code não envia menu. Na v2 esta porta responde 422 canal_sem_interativo, e nada é enviado." } ] } }, "listar": { "menu": { "grupo": "Templates", "nome": "Listar Templates aprovados", "metodo": "POST", "ativo": true, "resumo": "Lista os templates aprovados desta conexão, com as variáveis de cada um.", "caminho": "/v1/mensagens/templates" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": null, "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL" }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ] ], "respostas": [ { "codigo": "200", "titulo": "Quando há templates", "tom": "ok", "nota": "Só entram os aprovados na Meta e disponíveis nesta conexão. variaveis traz o nome de cada variável, e é o que vai em variaveis no envio.", "json": { "templates": [ { "nome": "codigo_verificacao_1", "idioma": "pt_BR", "categoria": "AUTHENTICATION", "variaveis": [ "1" ] } ] } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ] ], "notas": [ { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "Escolha antes de enviar", "texto": "Esta lista é a que o envio aceita agora. Template recusado pela Meta ou removido da conexão não aparece." } ] } }, "template": { "menu": { "grupo": "Templates", "nome": "Enviar Templates", "metodo": "POST", "ativo": true, "resumo": "Manda um template aprovado, com as variáveis dele.", "caminho": "/v1/mensagens/template" }, "detalhe": { "cabecalhos": [ [ "Content-Type", "application/json" ], [ "Accept", "application/json" ] ], "amostra": "", "corpo": { "token": "SEU_TOKEN", "conexao": "ID_DA_CONEXAO_OFICIAL", "para": "5581999999999", "template": "", "variaveis": {} }, "campos": [ [ "token", "texto", true, "O token do topo da tela." ], [ "conexao", "texto", true, "O identificador desta conexão." ], [ "para", "texto", true, "O telefone de destino, de 10 a 15 dígitos." ], [ "template", "texto", true, "O nome de um template aprovado desta conexão." ], [ "variaveis", "objeto", "cond", "O valor de cada variável do template, pela posição. Só é obrigatório se o template tiver variáveis; em template sem variável, omita o campo ou mande {}." ] ], "respostas": [ { "codigo": "202", "titulo": "Quando a Meta aceita", "tom": "ok", "nota": "conversa só vem preenchida quando já existia uma conversa viva e o template entrou nela. Enviar template não abre conversa: ela nasce quando o cliente responde. id é o que o webhook mensagem.status repete.", "json": { "status": "aceita", "id": "2d1c7a64-3d0a-4b1b-8f0a-0a9b2f6d5c10", "abriu_conversa": false, "conversa": null, "template": "" } }, { "codigo": "4xx", "titulo": "Quando ela recusa", "tom": "amb", "nota": "Toda recusa tem a mesma forma, e a causa é o que o outro lado lê para decidir se repete ou para. Nenhuma recusa envia mensagem pela metade.", "json": { "erro": "a frase para quem lê", "causa": "o código para quem programa" } } ], "erros": [ [ "401", "token", "Token ausente, inválido ou revogado.", true ], [ "401", "token_nao_aceito", "O token é de acesso pessoal ou de outra finalidade. Gere o token da empresa em Configurações > API REST.", true ], [ "403", "empresa_inativa", "A conta da empresa está suspensa, cancelada ou com o teste vencido. A API volta a responder quando a conta for regularizada.", true ], [ "404", "conexao_nao_encontrada", "Não existe conexão com esse identificador nesta empresa.", true ], [ "422", "conexao_incompativel", "A conexão não é do WhatsApp oficial. A v1 atende só a API oficial; a conexão por QR Code usa a v2.", true ], [ "422", "campo_invalido", "Faltou um campo ou ele veio fora do formato. A frase diz qual." ], [ "422", "conexao_desconectada", "A conexão existe, mas está desligada ou fora do ar.", false ], [ "429", "(sem causa)", "Mais de 60 chamadas por minuto neste token." ], [ "422", "variaveis", "variaveis não veio como objeto." ], [ "422", "numero_invalido", "O para não tem de 10 a 15 dígitos." ], [ "422", "template_nao_disponivel", "O template não existe, não está aprovado, ou não é desta conexão." ], [ "422", "variaveis_faltando", "Faltou o valor de alguma variável. Nada é enviado." ], [ "422", "template_desatualizado", "O texto foi alterado direto na Meta e o mapa de variáveis não vale mais." ], [ "422", "template_recusado_pela_meta", "A Meta recusou o envio. A frase traz o motivo dela." ], [ "422", "resultado_indeterminado", "A requisição saiu e a resposta se perdeu. Pode ter chegado.", true ], [ "429", "limite_do_plano", "O limite de envios da API no mês foi atingido. O cabeçalho Retry-After diz em quantos segundos volta.", true ], [ "503", "limite_nao_conferido", "Não deu para conferir o limite do plano agora. Nada foi enviado; tente de novo." ] ], "notas": [ { "tom": "t", "icone": "M21 3 10.5 13.5M21 3l-7 18-3.5-7.5L3 10z", "titulo": "O código de verificação sai por aqui", "texto": "E não pela tela Enviar Mensagem, que o recusa: código de verificação não é mensagem que atendente digita. O botão de copiar o código vai junto, preenchido com o mesmo valor da variável." }, { "tom": "a", "icone": "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18M12 8h.01M11 12h1v5h1", "titulo": "Só template aprovado", "texto": "Esta porta não tem campo de texto livre: fora da janela de 24 horas a Meta recusa, e dentro dela o texto vai em Enviar Mensagem." } ] } } } }