Skip to main content
skill CX Codex GP ChatGPT official · OpenAI

twilio-whatsapp-manage-senders — Codex skill: how to install

twilio-whatsapp-manage-senders is a Codex skill for registering and configuring WhatsApp Business senders through Twilio's Channels Senders API, including OTP verification and webhook setup.

MIT 1 installs ★ 8,052 updated 2026-10-08

Install into Codex · Skills CLI (Vercel) All methods and platforms ↓
npx skills add openai/plugins --skill twilio-whatsapp-manage-senders -a codex
Open on GitHub

What twilio-whatsapp-manage-senders does

This skill guides coding agents through registering WhatsApp Business senders with the Twilio SDK in Python or Node.js. It initiates number onboarding, verifies one-time passwords delivered by SMS or voice, and monitors sender states from CREATING to ONLINE.

It also configures profile metadata like business address, logo URL, and vertical. The skill updates incoming message callbacks and status webhooks. When senders drop OFFLINE, it inspects error arrays like reason 63020 to pinpoint Meta Business Manager issues.

Trial Twilio accounts cannot register production numbers. Verification requires an upgraded balance. Without Meta Business Verification, Twilio caps sender numbers at two.

What it helps with

  • register phone numbers for WhatsApp Business via Twilio Senders API
  • verify new senders using incoming SMS or voice OTP codes
  • configure inbound message endpoints and delivery status callbacks
  • populate WhatsApp business profiles with logos, addresses, and websites

Example prompts for the agent

  • Initiate WhatsApp registration for +15017122661 using SMS verification in Twilio
  • Submit verification code 123456 for sender SID XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Set the WhatsApp profile for our sender with company name Acme Support and webhook URLs

How to install twilio-whatsapp-manage-senders

1Skills CLI (Vercel)

npx skills add openai/plugins --skill twilio-whatsapp-manage-senders -a codex

2Manually: put the files in place

.agents/skills/twilio-whatsapp-manage-senders/SKILL.md

For all projects use ~/.agents/skills/

Step by step, with commands for each platform: Codex skills: how to install, where they live, how to call them

Questions about twilio-whatsapp-manage-senders

How to install twilio-whatsapp-manage-senders in Codex?

Run npx skills add openai/plugins --skill twilio-whatsapp-manage-senders -a codex in your terminal. You can also place the configuration in .agents/skills/twilio-whatsapp-manage-senders/SKILL.md.

What does twilio-whatsapp-manage-senders do?

It provides scripts and patterns to register WhatsApp Business senders, verify phone numbers via OTP, and manage webhooks using Twilio APIs.

How many senders can I register without Meta verification?

Unverified accounts can register up to 2 senders. Verified Meta Business Managers allow up to 20 senders, or 50 with an approved exception request.

Source text

SKILL.md · MIT
---
name: twilio-whatsapp-manage-senders
description: >
  Create, configure, and manage WhatsApp Business senders via Twilio's
  Channels Senders API. Covers programmatic sender registration, profile setup,
  webhook configuration, sender lifecycle statuses, and ISV flows. Use this
  skill to register and manage production WhatsApp senders at scale.
---

## Overview

A WhatsApp sender is a phone number registered with WhatsApp Business through Twilio. Registration goes through a lifecycle of statuses before becoming `ONLINE`. Sandbox testing does not require a registered sender — see `twilio-whatsapp-send-message`.

---

## Prerequisites

- Upgraded Twilio account (trial accounts cannot register production senders)
  — See `twilio-account-setup` for signup and upgrade steps
- A phone number capable of receiving SMS or voice verification
- Number must not already be registered with WhatsApp
- Environment variables:
  - `TWILIO_ACCOUNT_SID`
  - `TWILIO_AUTH_TOKEN`
  — See `twilio-iam-auth-setup` for credential setup and best practices
- SDK: `pip install twilio` / `npm install twilio`

---

## Quickstart

**Python**
```python
import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

# Step 1: Initiate registration
sender = client.messaging.v2.channels.senders.create(
    sender_id="whatsapp:+15017122661",
    verification_method="sms"
)
print(sender.sid)     # XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
print(sender.status)  # CREATING

# Step 2: Submit the OTP Twilio sends to the number
sender = client.messaging.v2.channels.senders(sender.sid).update(
    verification_code="123456"
)
print(sender.status)  # ONLINE (may pass through TWILIO_REVIEW first)
```

**Node.js**
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

// Step 1: Initiate registration
const sender = await client.messaging.v2.channels.senders.create({
    senderId: "whatsapp:+15017122661",
    verificationMethod: "sms",
});
console.log(sender.sid, sender.status);

// Step 2: Submit the OTP
const verified = await client.messaging.v2.channels.senders(sender.sid).update({
    verificationCode: "123456",
});
console.log(verified.status);
```

---

## Sender Lifecycle Statuses

| Status | Meaning |
|--------|---------|
| `CREATING` | Registration initiated |
| `PENDING_VERIFICATION` | Awaiting OTP submission |
| `VERIFYING` | OTP being validated |
| `TWILIO_REVIEW` | Under Twilio/Meta review |
| `ONLINE` | Active and ready to send |
| `OFFLINE` | Inactive — check `offlineReasons` |
| `DRAFT` | Incomplete registration |

---

## Key Patterns

### Set Business Profile

**Python**
```python
sender = client.messaging.v2.channels.senders(SENDER_SID).update(
    profile_name="Acme Support",
    profile_about="Official support channel for Acme Corp",
    profile_address="123 Main St, San Francisco, CA",
    profile_vertical="PROFESSIONAL_SERVICES",
    profile_logo_url="https://acme.com/logo.png",
    profile_websites=["https://acme.com"]
)
```

**Node.js**
```node
const sender = await client.messaging.v2.channels.senders(SENDER_SID).update({
    profileName: "Acme Support",
    profileAbout: "Official support channel for Acme Corp",
    profileAddress: "123 Main St, San Francisco, CA",
    profileVertical: "PROFESSIONAL_SERVICES",
    profileLogoUrl: "https://acme.com/logo.png",
    profileWebsites: ["https://acme.com"],
});
```

### Configure Webhooks

**Python**
```python
sender = client.messaging.v2.channels.senders(SENDER_SID).update(
    callback_url="https://yourapp.com/whatsapp/inbound",
    callback_method="POST",
    status_callback_url="https://yourapp.com/whatsapp/status"
)
```

**Node.js**
```node
await client.messaging.v2.channels.senders(SENDER_SID).update({
    callbackUrl: "https://yourapp.com/whatsapp/inbound",
    callbackMethod: "POST",
    statusCallbackUrl: "https://yourapp.com/whatsapp/status",
});
```

### Retrieve and List Senders

**Python**
```python
sender = client.messaging.v2.channels.senders(SENDER_SID).fetch()
print(sender.status)

for s in client.messaging.v2.channels.senders.list():
    print(s.sid, s.status)
```

**Node.js**
```node
const sender = await client.messaging.v2.channels.senders(SENDER_SID).fetch();
const senders = await client.messaging.v2.channels.senders.list();
senders.forEach(s => console.log(s.sid, s.status));
```

If a sender is `OFFLINE`, check the `offlineReasons` array in the response (e.g. code `63020` means business hasn't accepted Twilio's Meta invitation).

### Migrate an Existing WhatsApp Number

If a number is already registered on WhatsApp (personal or business):
1. Check: `https://wa.me/<PHONE_NUMBER>?text=hi`
2. Delete the existing WhatsApp account on the device, or disable 2FA on the competing platform
3. Proceed with registration above

### ISV / Tech Provider Flow

Register senders under a client's WhatsApp Business Account (WABA):

**Python**
```python
sender = client.messaging.v2.channels.senders.create(
    sender_id="whatsapp:+15017122661",
    waba_id="client-waba-id"
)
```

**Node.js**
```node
const sender = await client.messaging.v2.channels.senders.create({
    senderId: "whatsapp:+15017122661",
    wabaId: "client-waba-id",
});
```

The client must accept Twilio's invitation in their Meta Business Manager.

---

## CANNOT

- **Cannot register a phone number to multiple WABAs** — Each number belongs to one WABA at a time
- **Cannot exceed 2 senders without Meta Business Verification** — Unverified accounts are limited to 2
- **Cannot exceed 20 senders without exception** — Verified Meta Business Manager: max 20 (50 with exception request)
- **Cannot verify phone number only via SMS** — Voice verification is available if SMS cannot be received

---

## Next Steps

- **Send WhatsApp messages with this sender:** `twilio-whatsapp-send-message`
- **Create message templates:** `twilio-content-template-builder`
- **Send WhatsApp OTPs:** `twilio-verify-send-otp`

© Twilio · MIT · openai/plugins

Similar skills

All skills for Backend and APIs →

From the same set567

The whole set →
building-ai-agent-on-cloudflare building-ai-agent-on-cloudflare generates Cloudflare Agents SDK code for edge deployment on Workers and Durable Objects. Handles persistent state, WebSockets, and background scheduling. CX Codex GP ChatGPT +1 2installs vercel-connect vercel-connect guides Codex and ChatGPT to fetch scoped OAuth tokens for Slack, GitHub, Snowflake, and MCP servers using Vercel OIDC. CX Codex GP ChatGPT +1 1installs knowledge-update knowledge-update injects up-to-date Vercel platform facts into the session and overrides stale model knowledge. Useful when your agent still reaches for Edge Functions or vercel.json. CX Codex GP ChatGPT +1 1installs eve Skill for working with eve, a framework for durable AI agents. Creates projects, debugs deployed agents, and picks architecture for eve-based applications. CX Codex GP ChatGPT +1 1installs twilio-voice-conversation-relay The twilio-voice-conversation-relay skill builds voice AI agents on Twilio, handling speech recognition and synthesis over WebSocket. CX Codex GP ChatGPT +1 1installs twilio-send-message twilio-send-message — a skill that gives your agent the recipes for sending messages through Twilio's Programmable Messaging API — SMS, MMS, RCS and WhatsApp. Useful when a project needs notifications or alerts. CX Codex GP ChatGPT +1 1installs twilio-messaging-overview twilio-messaging-overview is a Codex skill that compares Twilio Messaging channels and walks through setup. It covers SMS, WhatsApp, RCS, and Facebook Messenger, from the first message to delivery monitoring. CX Codex GP ChatGPT +1 1installs twilio-account-setup twilio-account-setup walks you from Twilio signup to your first sent message: credentials, phone number, SDK, subaccounts. CX Codex GP ChatGPT +1 1installs

Project sponsors

Companies that keep this analytics open