# Vobiz Whatsapp

> Send and receive messages on the WhatsApp Business API via Vobiz - message templates, broadcast campaigns, inbound webhooks, multi-agent inbox, and BYON channel setup.

- **Type:** Skill
- **Install:** `agentstack add skill-vobiz-ai-agent-skills-vobiz-whatsapp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vobiz-ai](https://agentstack.voostack.com/s/vobiz-ai)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vobiz-ai](https://github.com/vobiz-ai)
- **Source:** https://github.com/vobiz-ai/Agent-Skills/tree/main/skills/vobiz-whatsapp

## Install

```sh
agentstack add skill-vobiz-ai-agent-skills-vobiz-whatsapp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Vobiz WhatsApp skill

Use this when the user wants to **send WhatsApp messages programmatically, build a chatbot, run a campaign, or set up multi-agent customer support over WhatsApp**.

## How Vobiz fits

Vobiz is a Meta-approved BSP (Business Solution Provider). You connect your WhatsApp Business Account (WABA) once, then send/receive via Vobiz's REST API or no-code campaign builder.

## Capabilities

- **Messaging** - send `text`, `template`, and media (`image`, `audio`, `video`, `document`, `sticker`) via `POST /api/v1/messaging/messages`. Interactive (buttons, lists), `location`, and `contacts` are WhatsApp message types you **receive inbound**; the documented send contract covers the types above.
- **Templates** - submit + manage Meta-approved templates, scoped per channel under `/channels/{channelId}/templates`
- **Inbox** - multi-agent dashboard for conversation handling
- **Webhooks** - outbound events `message.inbound`, `message.status` (status = `sent`/`delivered`/`read`/`failed`), and `call.`; signed with `X-Webhook-Signature`
- **Channels** - three onboarding modes: `bring_your_own` (BYON), `buy_from_vobiz`, `embedded_signup`
- **Numbers** - search/buy WhatsApp-capable numbers, or OTP-verify a BYON number before connecting

## Core request shape (send a message)

Every send needs `channel_id` (UUID), `waba_id`, `to` (E.164 with leading `+`), and `type`. The send endpoint returns `201` with a `Message` object whose `status` starts at `pending` and is updated to `sent` → `delivered` → `read` (or `failed`) via `message.status` webhooks. The Meta id arrives as `meta_message_id` (the `wamid`) once Meta accepts it — `null` until then.

```json
{ "channel_id": "", "waba_id": "", "to": "+919876543210",
  "type": "text", "text": { "body": "Hi!" } }
```

Media uses a single `media` object with either `link` (public HTTPS) **or** Meta media `id`, plus optional `caption`/`filename`. Templates use `type: "template"` with `template.name`, `template.language.code`, and `components[]` carrying ordered `parameters`.

## Key restrictions

- **24-hour customer-service window**: free-form messages (text/media/interactive) are allowed only for 24h after the customer's **last inbound** message. Each new inbound message resets the timer. Outside the window, you can send **only approved templates** — a free-form send will be rejected. Sending a template opens a fresh 24h window.
- **Templates** must be pre-approved by Meta. New templates start at `PENDING_REVIEW`; approval takes minutes to ~24h. After approving (or editing) in Meta Business Manager directly, call `POST /channels/{channelId}/templates/sync` to pull the new status into Vobiz.
- **One BSP per number**: a WhatsApp number can be on exactly one BSP at a time. Moving from Twilio/Wati/etc. requires deregistering it there first; the number cannot be live on the WhatsApp/WhatsApp Business consumer app.
- **Quality rating + tiers**: Meta assigns a Green/Yellow/Red quality rating and a daily messaging limit per number. Low quality or high block/report rates reduce limits and can pause templates.

## Pitfalls

- **First message to a new contact must be a template.** A brand-new contact has never replied, so the 24h window is closed — a free-form `text` send fails. Use an approved template (often `UTILITY` or `MARKETING`) to open the conversation.
- **`delivered`/`read` are not events.** They are values of the `status` field inside a single `message.status` webhook. There is no `message.delivered`/`message.read`/`message.sent`/`message.failed`, nor `contact.updated`/`campaign.completed`. Only three outbound event types exist: `message.inbound`, `message.status`, `call.`.
- **Verify `X-Webhook-Signature` over the raw bytes.** It is the hex HMAC-SHA256 of the exact request body keyed by your subscription `secret` — **no** `sha256=` prefix. Do not re-serialize parsed JSON before hashing. (The Meta→Vobiz leg uses `X-Hub-Signature-256` with a `sha256=` prefix — different mechanism, you don't build against it.)
- **Two webhook systems.** Meta→Vobiz (platform plumbing, set once in your Meta App) is separate from Vobiz→your-server (what you build against). The `secret` is never returned after creation — store it when you create the subscription.
- **Template category mismatch = rejection.** Don't ship promotional content as `UTILITY`. `AUTHENTICATION` is OTP-only and gets the `COPY_CODE` button + expedited review.
- **`access_token` is write-only.** The Meta system-user token (starts with `EAA…`) is stored securely and never returned by any channel API. Rotate it via `PUT /channels/whatsapp/{id}` when it expires.
- **Deduplicate on `event_id`.** Deliveries are retried; the underlying Meta event can also repeat. Return `200` fast and process async.

## Recipes

- **Auto-reply to an inbound message**: receive `message.inbound` → reply with `type: "text"` (you're inside the 24h window). See `whatsapp/webhooks/events` + `whatsapp/api/send-message`.
- **Proactive notification (window closed)**: create + get an approved template → send with `type: "template"` and ordered `components[].parameters`. See `whatsapp/messaging/templates`.
- **Connect an existing number (BYON)**: `POST /numbers/whatsapp/bring-your-own/verify` (sms/voice OTP) → `…/confirm` with the code → `POST /channels/whatsapp` with `number_onboarding_mode: "bring_your_own"`, `waba_id`, `phone_number_id`, `access_token`. See `whatsapp/channels/byon` + `whatsapp/api/numbers`.
- **Track delivery**: store the returned `id`/`meta_message_id`, then correlate `message.status` webhooks by the `wamid` in `statuses[].id`.

## When to search docs

- "Send a template message" → `whatsapp/messaging/templates`, `whatsapp/api/send-message`
- "Inbound webhook / verify signature" → `whatsapp/webhooks`, `whatsapp/webhooks/events`
- "Port my number to Vobiz" → `whatsapp/channels/byon`, `whatsapp/api/numbers`
- "Connect a channel via API / embedded signup" → `whatsapp/api/channels`
- "Build a chatbot flow" → `whatsapp/messaging`
- "Buy a WhatsApp number" → `whatsapp/api/numbers`
- "Pricing / per-message fees" → `whatsapp/getting-started/introduction`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vobiz-ai](https://github.com/vobiz-ai)
- **Source:** [vobiz-ai/Agent-Skills](https://github.com/vobiz-ai/Agent-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vobiz-ai-agent-skills-vobiz-whatsapp
- Seller: https://agentstack.voostack.com/s/vobiz-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.