WhatsApp Business API for team broadcast — create whatsapp group

Use case overview

This scenario uses the groups API with a create operation to provision a named WhatsApp group for team broadcasts. No 24-hour session window is required because the call is a channel management action.

Template example

Internal group created for sales broadcast — share the invite link with your team.

Group creation is a management API call — not a session message; webhook is disabled for this profile.

When to use it

• internal sales broadcast

Business value

• Team setup event fires from CRM or internal admin workflow
• groups create provisions Sales team Q1 with internal broadcast description
• Invite link is retrieved and stored for distribution
• Managers join the WhatsApp group via the invite URL
• Broadcast campaigns can target the group from approved tooling

Workflow

1. An admin or CRM event triggers team group provisioning.
2. groups create sets the group name and internal broadcast description.
3. The API returns group metadata including the invite link.
4. Your system shares the invite URL with authorised team members.
5. Delivery progress is reported asynchronously — typically sent, then delivered (or failed/undelivered).
6. Your system receives status via webhook (hooks[]) or polls delivery status and handles failures if needed.

Technical implementation

Prerequisites

• 1MSG channel with groups management permissions.
• Backend workflow to store and distribute the returned invite link securely.

Code examples

#!/usr/bin/env node

// === Configuration (replace "___" placeholders) ===
const API_BASE_URL = "https://api.1msg.io"; // production 1MSG API base URL
const CHANNEL_ID = "___";                   // channel ID from 1MSG dashboard
const API_TOKEN = "___";                    // channel JWT token (Bearer)



async function createWhatsAppGroup() {
  const url = `${API_BASE_URL}/${CHANNEL_ID}/groups`;
  const requestBody = {
    groupName: "Sales team Q1",
    description: "Internal broadcast",
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });

  const raw = await res.text();
  let data;
  try {
    data = JSON.parse(raw);
  } catch {
    data = null;
  }

  if (!res.ok || !data || data.created !== true) {
    console.error("Send failed.");
    console.error(raw);
    process.exit(1);
  }

  console.log("API response:", raw);
  return data;
}

if (require.main === module) {
  createWhatsAppGroup().catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { createWhatsAppGroup };

Immediate API response (synchronous)

• HTTP 2xx and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone.
• Save the `id` field from the response (value looks like wamid.…). Use it to correlate delivery callbacks or polling.
• The response may also include message and description — informational only.

Delivery status (asynchronous)

• Register a webhook (POST …/webhook) so 1MSG POSTs delivery updates to your HTTPS endpoint in a separate `hooks[]` payload (sent, delivered, read, or failed/undelivered when applicable).
• Optionally poll: GET {base}/{channel}/hookInfo?messageId=<id from sendTemplate>.
• In practice, delivery often completes within a few seconds — but that is not guaranteed by the API contract.

Common errors

• Session window closed (no client message within 24 hours)
• Invalid or non-normalized phone number
• Missing or invalid message body / media URL
• Delivery failure — check status webhook and retry policy

FAQ

• Do I need a template? No — this scenario uses a session message inside the 24-hour customer service window.
• When does the session window close? If the client has not written or replied within 24 hours, sendMessage will fail until a template reopens the chat.
• How do I check delivery? sent: true only confirms acceptance. Track delivery via webhook hooks[] or polling.
• What if the message is not delivered? Log the failed/undelivered hook, verify the session window, then retry or use a template.
• Can I connect this to my CRM or backend? Yes — trigger the API call from your inbound webhook or workflow engine.

Related

• Knowledge base
• Creating a template
• Sending a template
• SDK