stuntman / providers / whatsapp

WhatsApp

Meta's WhatsApp Cloud API with templates, the 24-hour window, simulated people and signed webhooks.

Stands in for

  • Meta WhatsApp Cloud API (Graph)
  • WhatsApp Business webhooks

Everything WhatsApp gives you

  1. 01

    Conversations per number

    One row per number with the last message, the person's profile name and whether the 24 h window is open.

  2. 02

    The 24-hour window

    Outside the window only templates are delivered; a free text fails with 131047, as Meta reports it.

  3. 03

    Templates with review states

    Approved, pending, rejected, paused or disabled; each change sends message_template_status_update to the app.

  4. 04

    Parameters checked

    A wrong parameter count answers 132000; an undeclared template 132001, and it is listed so you can add it.

  5. 05

    People who reply

    reply_as_user sends a text, a template button tap, an image or a location as Meta's messages webhook.

  6. 06

    Signed webhooks

    Status and message webhooks carry X-Hub-Signature-256 with your app secret; the verification GET runs on demand.

  7. 07

    Tier, throughput, quality

    Over the throughput: 130429. Over the tier: 131056. A restricted number: 131048. Low template quality pauses it.

  8. 08

    Recipients per number

    Whether a number has WhatsApp, its profile name and the steps each message goes through: sent, delivered, read, failed.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

A conversation, as Meta would report it

A conversation, as Meta would report it: the WhatsApp screen in Stuntman
1Customer service window

Open for 24 h after the person's last message; outside it only templates go out.

1 of 5
2Failed 131047

A free text sent outside the window fails, and the status webhook says so.

2 of 5
3Template with buttons

The template as the person sees it, with its URL and quick-reply buttons.

3 of 5
4Status, as the app saw it

accepted, sent, delivered, read: each webhook with what your app answered.

4 of 5
5Provoke on this message

Fail it with a Meta error code, or send the read webhook again.

5 of 5
  1. Customer service window

    Open for 24 h after the person's last message; outside it only templates go out.

  2. Failed 131047

    A free text sent outside the window fails, and the status webhook says so.

  3. Template with buttons

    The template as the person sees it, with its URL and quick-reply buttons.

  4. Status, as the app saw it

    accepted, sent, delivered, read: each webhook with what your app answered.

  5. Provoke on this message

    Fail it with a Meta error code, or send the read webhook again.

Templates and their review state

Templates and their review state: the WhatsApp screen in Stuntman
1Rejected and paused

Sends follow the status: a paused template answers 132015, a disabled one 132016.

1 of 5
2Asked for, not declared

The app used a template that does not exist; Stuntman answered 132001.

2 of 5
3Status

Change it and Stuntman sends message_template_status_update to the app.

3 of 5
4Quality

Low quality pauses the template, as Meta does.

4 of 5
5Variables checked

The values the app sent last; a wrong count is answered 132000.

5 of 5
  1. Rejected and paused

    Sends follow the status: a paused template answers 132015, a disabled one 132016.

  2. Asked for, not declared

    The app used a template that does not exist; Stuntman answered 132001.

  3. Status

    Change it and Stuntman sends message_template_status_update to the app.

  4. Quality

    Low quality pauses the template, as Meta does.

  5. Variables checked

    The values the app sent last; a wrong count is answered 132000.

Number, access and webhook

Number, access and webhook: the WhatsApp screen in Stuntman
1Expire tokens now

Every Graph call gets 190 OAuthException until tokens are restored.

1 of 5
2Signed with the app secret

Webhooks carry X-Hub-Signature-256, so the app's check is tested.

2 of 5
3Verification request

Sends Meta's hub.challenge GET and checks the app echoes it.

3 of 5
4Messaging tier

Unique numbers a day; over it the send fails with 131056.

4 of 5
5number.yaml

The same settings as a file: ids, access, webhook, limits and quality.

5 of 5
  1. Expire tokens now

    Every Graph call gets 190 OAuthException until tokens are restored.

  2. Signed with the app secret

    Webhooks carry X-Hub-Signature-256, so the app's check is tested.

  3. Verification request

    Sends Meta's hub.challenge GET and checks the app echoes it.

  4. Messaging tier

    Unique numbers a day; over it the send fails with 131056.

  5. number.yaml

    The same settings as a file: ids, access, webhook, limits and quality.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • 500 on the next send

    Graph error #131000, for count sends

    force_whatsapp_failure {answer: 500}
  • 400 invalid parameter

    Graph error #100

    force_whatsapp_failure {answer: 400}
  • Broken connection

    The connection resets, answers nothing, or hangs

    force_whatsapp_failure reset | empty | timeout
  • Expired token

    Every Graph call gets 190 "Session has expired"

    expire_whatsapp_tokens
  • Not on WhatsApp

    The status webhook reports 131026

    set_recipient {whatsapp: false}
  • Outside the window

    A free text after 24 h without a reply fails 131047

    send a text while get_window says closed
  • Template paused

    Sends with it fail 132015; disabled gives 132016

    set_template_status paused
  • Failed with a code

    A sent message turns failed with the Meta error you pick

    set_message_status {status: failed}
  • Duplicate status webhook

    The same status webhook arrives again

    resend_status
  • Bad webhook signature

    Wrong, missing or old secret, or a replay; returns your status

    send_bad_webhook
  • Rate limit

    Sends over the throughput get 130429

    set_whatsapp_number {throughput}

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Make sure the order confirmation flow works when the customer taps "Talk to us".

wait_for_whatsapp{"number": "+1 415 555 0142", "template": "order_confirmation"}
→ ok wamid.HBgL…A1E0 sent by acme-api, 4 parameters
reply_as_user{"number": "+1 415 555 0142", "button": "Talk to us"}
→ ok messages webhook signed, acme-api answered 200; window open for 24 h

MCP tools

  • list_whatsapp_messagesMessages both ways, with status history and the window
  • wait_for_whatsappWait for the app to send to a number; returns it
  • reply_as_userThe person replies: text, button, image or location
  • set_message_statusMove a message to sent, delivered, read or failed
  • get_windowIs the 24 h window open for a number, and until when
  • set_template_statusApprove, reject, pause or disable a template
  • force_whatsapp_failureThe next sends fail: 500, 400, reset, empty, timeout
  • send_bad_webhookA webhook the app must reject
  • expire_whatsapp_tokensEvery Graph call gets 190 until restored

The same over HTTP

  • GET/api/whatsapp/messages
  • GET/api/whatsapp/wait
  • POST/api/whatsapp/numbers/{number}/reply
  • POST/api/whatsapp/force
  • POST/api/whatsapp/number/webhook/bad