Wow! Redução de 65% no preço para clientes brasileiros! Registre-se agora
Boas-vindas na entrada · caso de uso WhatsApp API

Mensagens de boas-vindas em um grupo do WhatsApp quando alguém entra

Novos membros podem ver a mesma mensagem de onboarding no chat do grupo, no privado ou nos dois, sem um admin digitar manualmente. Quando um participante entra, seu backend ou automação mapeia o id do grupo para o texto certo e envia via Whapi.Cloud. Este caso de uso mostra a integradores como implementar esse fluxo com a WhatsApp API.

Começa com webhook de entrada no grupo Mensagem pública no grupo e/ou chat privado
Painel de admin da comunidade ao lado de um telefone cujo chat de grupo WhatsApp mostra uma mensagem de boas-vindas logo após alguém entrar.
Cenário de uso

Quando usar este fluxo

Um webhook de entrada deve iniciar as boas-vindas

Use este fluxo quando o webhook do canal entrega um evento de entrada de participante no grupo e seu worker deve reagir, não quando você só envia texto por clique manual.

Você gerencia vários grupos com textos de boas-vindas diferentes

Use este fluxo quando cada id de grupo mapeia para regras próprias, DM privado ou ambos, não quando um único texto serve para todas as comunidades.

n8n, Make ou seu backend controlam dedupe e timing

Use este fluxo quando own_backend, n8n ou Make deduplicam eventos de entrada e escolhem entrega pública ou privada, não quando a aprovação de entrada ainda está pendente.

Chat de grupo WhatsApp no telefone com mensagem de boas-vindas logo após um novo membro entrar.
Experiência do cliente

Novos membros se sentem bem-vindos na hora

Sem automação, admins esquecem de cumprimentar ou colam regras diferentes a cada vez, e quem entra não sabe qual é o próximo passo.

Depois do fluxo, o grupo pode ver um olá público e regras enquanto o recém-chegado recebe uma nota privada com links ou instruções. Integradores constroem esse resultado com a WhatsApp API.

Fluxo de trabalho

Do evento de entrada às boas-vindas

1

Um participante entra no grupo

Whapi envia um evento de participante do grupo para a URL do seu webhook. own_backend, n8n ou Make lê o id do grupo e do recém-chegado, deduplica payloads duplicados de entrada e carrega o texto de boas-vindas daquele grupo.

2

Enviar o texto de boas-vindas

POST /messages/text

sendMessageText publica as boas-vindas configuradas. Coloque o id @g.us do grupo ou o chat do recém-chegado em to e a mensagem em body. Chame uma vez para boas-vindas públicas, uma para nota privada, ou duas vezes se ambas se aplicarem.

Precisa rastrear entrega? Uma resposta de API bem-sucedida não significa que todos já veem as boas-vindas no chat. Saiba mais sobre status de entrega →

Pré-requisitos

Antes de executar o fluxo

Conecte o número WhatsApp que administra ou envia nesses grupos, ative webhooks do canal para eventos de participantes e autentique cada envio com o token API desse número. Dedupe, texto por grupo e lógica n8n ou Make ficam fora da Whapi.

Opcional — aprofundar neste fluxo

Implementação API

Uma chamada entrega as boas-vindas

Esta chamada é como o texto de onboarding chega ao chat do grupo ou ao chat privado do recém-chegado depois que seu worker trata o webhook de entrada.

Obtenha seu token API grátis após registrar-se em whapi.cloud e use esse token no código em vez de Your_Token dos exemplos.

Enviar o texto de boas-vindas

Envie o texto de boas-vindas configurado ao grupo ou ao novo participante para onboarding na entrada sem post manual.

curl --request POST \
     --url https://gate.whapi.cloud/messages/text \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token' \
     --header 'content-type: application/json' \
     --data '
{
  "to": "[email protected]",
  "body": "Welcome to the group! Read the rules below and say hello."
}
'
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://gate.whapi.cloud/messages/text",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"to\":\"[email protected]\",\"body\":\"Welcome to the group! Read the rules below and say hello.\"}",
  CURLOPT_HTTPHEADER => [
    "accept: application/json",
    "authorization: Bearer Your_Token",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests

url = "https://gate.whapi.cloud/messages/text"
payload = {
    "to": "[email protected]",
    "body": "Welcome to the group! Read the rules below and say hello."
}
headers = {
    "accept": "application/json",
    "authorization": "Bearer Your_Token",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
const response = await fetch('https://gate.whapi.cloud/messages/text', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: 'Bearer Your_Token',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    to: '[email protected]',
    body: 'Welcome to the group! Read the rules below and say hello.',
  }),
});

console.log(await response.text());
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"to\":\"[email protected]\",\"body\":\"Welcome to the group! Read the rules below and say hello.\"}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/messages/text")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();
using RestSharp;

var options = new RestClientOptions("https://gate.whapi.cloud/messages/text");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddHeader("content-type", "application/json");
request.AddJsonBody(new { to = "[email protected]", body = "Welcome to the group! Read the rules below and say hello." });
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"to":"[email protected]","body":"Welcome to the group! Read the rules below and say hello."}`)
	req, _ := http.NewRequest("POST", "https://gate.whapi.cloud/messages/text", bytes.NewReader(body))
	req.Header.Set("accept", "application/json")
	req.Header.Set("authorization", "Bearer Your_Token")
	req.Header.Set("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
Envio

Saiba quando as boas-vindas chegaram

Uma resposta de envio bem-sucedida não significa que o destinatário já tem a mensagem de boas-vindas. O primeiro status visível antes de um webhook é pending. Mudanças posteriores chegam só em statuses.post e statuses.put. Se o status permanecer pending e não avançar para sent, delivered ou ack posterior, a mensagem não foi entregue. Verifique o payload e a permissão da conta para enviar esse tipo.

  • Uma resposta de sendMessageText não prova que as boas-vindas estão visíveis no chat.

  • pending que não avança significa que as boas-vindas não foram entregues.

  • Observe statuses.post e statuses.put para acks posteriores em cada perna.

  • Tente de novo ou alerte separadamente quando a perna pública do grupo falha mas a privada teve sucesso.

O que ler sobre entrega e webhooks

Fale com nosso suporte se algo deu errado
Quando algo falha

Trate falhas em cada etapa

Webhooks de entrada duplicados, JID de grupo errado na config ou boas-vindas rejeitadas ou não entregues devem ser deduplicados, ignorados, reenviados ou alertados em vez de considerar o onboarding concluído.

Entrada detectada, mas boas-vindas falharam?

Deduplique por id de participante e id de grupo antes do envio. Se o JID do grupo for desconhecido, registre, pule e alerte ops em vez de postar em outro lugar. Quando sendMessageText for rejeitado ou não entregue, reenvie com backoff e alerte; trate pernas pública e privada de forma independente. Se a entrega ainda falhar após retry, contate o suporte Whapi com o id do canal e a resposta falha.

Fale com nosso suporte se algo deu errado

Diagnosticar por etapa da API

Situação O que significa O que fazer
400 Wrong request parameters Parâmetros de solicitação incorretos — verifique to e body no payload de boas-vindas.
401 Need channel authorization for send message
402 Trial version limit exceeded
403 It is forbidden to send to this group/recipient É proibido enviar a este grupo ou destinatário — confirme o JID do grupo, id do chat do recém-chegado e permissões do canal.
429 Too many requests
500 Internal Error
Perguntas frequentes

Perguntas de integradores

Não. Moderação de entrada aprova ou rejeita pedido pendente antes de alguém entrar. Este fluxo roda quando o participante já está no grupo e envia o texto de boas-vindas.
Não. Invite-after-payment resolve link de convite para o pagador. Aqui o gatilho é evento de entrada e a ramificação é texto de boas-vindas no grupo e/ou chat privado.
Deduplique por id de participante e id de grupo antes do send. Trate webhook duplicado como onboarding incompleto até seu worker confirmar que o primeiro envio teve sucesso.
Sim. Mapeie cada grupo ao modo de entrega em own_backend, n8n ou Make, depois chame sendMessageText com JID do grupo, chat do recém-chegado ou ambos em requisições separadas.
Não para este copy de onboarding personalizado. Você compõe o corpo e envia com sendMessageText. Considere regras de template só se mudar depois para convite ou mensagem utilitária baseada em template em outro fluxo.
Recursos compatíveis do WhatsApp

Tudo o que você precisa para criar automações no WhatsApp

O Whapi.Cloud oferece acesso a um conjunto completo de recursos do WhatsApp — mensagens, mídia, grupos, canais, webhooks e muito mais. Crie bots, automações e integrações sem limitações de funcionalidades.

Escolhido por desenvolvedores

Confiado por mais de 3.300 desenvolvedores e equipes SaaS

Desenvolvedores no mundo inteiro utilizam o Whapi.Cloud para criar automações, bots, integrações com CRM, ferramentas de envio em massa e fluxos avançados de WhatsApp. Nossa infraestrutura processa milhões de requisições API com alta estabilidade — e esse número cresce a cada mês.

Ícone de recurso

5,5K+

canais de API ativos

Ícone de recurso

21M+

requisições API por mês

“Tudo é simples, intuitivo e fácil de navegar. A documentação é clara e todas as informações estão bem à mão. Trabalho excelente.”

Roberto K. / Desenvolvedor Web

“Conectamos o WhatsApp aos nossos fluxos usando o n8n em apenas alguns minutos. Sem código, sem complicações — funcionou de primeira.”

Martin P. / Desenvolvedor

“O Whapi.Cloud se tornou uma parte essencial da nossa comunicação com clientes. Automatizamos atualizações de produtos, notificações de pedidos e mensagens de suporte — tudo sem templates nem aprovações da Meta.”

Oscar T. / CTO

Balão decorativo