Wow! Build your WhatsApp integration. Start free. Register Now
Group join welcome · WhatsApp API use case

Welcome messages in a WhatsApp group when someone joins

New members can see the same onboarding message every time, in the group chat, in private, or both, without an admin typing it by hand. When a participant joins, your backend or automation can map the group id to the right copy and send it through Whapi.Cloud. This use case shows integrators how to implement that flow through the WhatsApp API.

Starts on a group join webhook Public group message and/or private chat
Community admin dashboard beside a phone whose WhatsApp group chat shows a welcome message right after someone joined.
Use case

When to use this flow

A join webhook should start the welcome

Use this flow when your channel webhook delivers a group participant join event and your worker should react, not when you only send text on a manual button click.

You run several groups with different welcome copy

Use this flow when each group id maps to its own rules text, private DM text, or both, not when one static blast fits every community.

n8n, Make, or your backend owns dedupe and timing

Use this flow when own_backend, n8n, or Make dedupes join events and chooses public versus private delivery, not when join approval is still pending.

WhatsApp group chat on a phone showing a fresh welcome message right after a new member joined.
Customer experience

New members feel welcomed right away

Without automation, admins forget to greet newcomers or paste different rules each time, so people join a busy group with no clear next step.

After the flow runs, the group may see a public hello and rules while the newcomer can also get a private note with links or instructions in chat. Integrators build this result with the WhatsApp API.

Workflow

From join event to welcome

1

A participant joins the group

Whapi sends a group participant event to your webhook URL. own_backend, n8n, or Make reads the group id and newcomer id, dedupes duplicate join payloads, and loads the welcome copy for that group.

2

Send the welcome text

POST /messages/text

sendMessageText posts the configured welcome. Put the group @g.us id or the newcomer's chat id in to and the message in body. Call once for a public welcome, once for a private note, or twice when both apply.

Need delivery tracking? A successful API response does not mean everyone already sees the welcome in chat. Learn about delivery status →

Prerequisites

Before you run the flow

Connect the WhatsApp number that administers or sends in these groups, enable channel webhooks for participant events, and authenticate every send with that number's API token. Dedupe, per-group copy, and n8n or Make logic stay outside Whapi.

Optional — go deeper for this flow

API implementation

One call delivers the welcome

This call is how onboarding text reaches the group chat or the newcomer's private chat after your worker handles the join webhook.

Get your API token for free after you register on whapi.cloud, and use that token in the code instead of Your_Token from the examples.

Send the welcome text

Send the configured welcome text to the group or the new participant so join onboarding happens without a manual post.

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))
}
Delivery

Know when the welcome landed

A successful send response does not mean the recipient already has the welcome message. The first status visible before a webhook is pending. Later status changes arrive only on statuses.post and statuses.put. If the status stays pending and does not move to sent, delivered, or a later ack, the message was not delivered. Check the payload and the account's permission to send that type.

  • A response from sendMessageText is not proof the welcome is visible in chat.

  • pending that never moves on means the welcome was not delivered.

  • Watch statuses.post and statuses.put for later acks on each leg.

  • Retry or alert separately when the public group leg fails but the private leg succeeded.

What to read on delivery and webhooks

Contact our support if something went wrong
When things break

Handle failures at each step

Duplicate join webhooks, a wrong group JID in config, or a rejected or undelivered welcome must be deduped, skipped, retried, or alerted instead of treating onboarding as done.

Join detected, but welcome failed?

Dedupe by participant id and group id before send. If the group JID is unknown, log, skip, and alert ops instead of posting elsewhere. When sendMessageText is rejected or not delivered, retry with backoff and alert; handle the public and private legs independently. If welcome delivery still fails after a retry, contact Whapi support with the channel id and the failed send response.

Contact our support if something went wrong

Troubleshoot by API step

Status What it means What to do
400 Wrong request parameters Wrong request parameters — check to and body on the welcome payload.
401 Need channel authorization for send message
402 Trial version limit exceeded
403 It is forbidden to send to this group/recipient It is forbidden to send to this group or recipient — confirm the group JID, newcomer chat id, and channel permissions.
429 Too many requests
500 Internal Error
FAQ

Questions integrators ask

No. Join moderation approves or rejects a pending request before someone enters. This flow runs after a participant is already in the group and sends welcome copy.
No. Invite-after-payment resolves an invite link for a payer. Here the trigger is a join event and the branch is welcome text in the group and/or private chat.
Dedupe by participant id and group id before you call send. Treat a duplicate webhook as incomplete onboarding until your worker confirms the first send succeeded.
Yes. Map each group to delivery mode in own_backend, n8n, or Make, then call sendMessageText with the group JID, the newcomer's chat id, or both in separate requests.
No for this custom onboarding copy. You compose the welcome body and send it with sendMessageText. Keep template-library rules in mind only if you later switch to a template-based invite or utility message for a different flow.
Supported WhatsApp Features

Everything you need to build WhatsApp automation

Whapi.Cloud gives you access to a complete set of WhatsApp features — messaging, media, groups, channels, webhooks and more. Build bots, automations and integrations without feature limitations.

Chosen by developers

Trusted by 3,300+ developers and SaaS teams

Developers worldwide rely on Whapi.Cloud to build automations, bots, CRM integrations, bulk messaging tools and advanced WhatsApp workflows. Our infrastructure processes millions of API requests with high stability — and grows every month.

Icon of feature

5,5K+

active API channels

Icon of feature

21M+

API requests processed monthly

“Everything is simple, intuitive and easy to navigate. The docs are clear, and all the info I need is right on the screen. Great job.”

roberto k. / Web Developer

“We connected WhatsApp to our workflows using n8n in just a few minutes. No code, no complications- everything worked on the first try.”

Martin p. / Developer

“Whapi.Cloud became a key part of our customer communication. We automated product updates, order notifications and support messages without needing Meta templates or approvals”

Oscar T. / CTO

Decorative bubble