stuntman / providers / sms

SMS

A Zenvia SMS gateway that keeps every text, walks it through delivery steps and lets the person text back.

Stands in for

  • Zenvia API v2
  • Zenvia status and message webhooks

Everything SMS gives you

  1. 01

    See every text

    Every send, refusal and reply, newest first, with its encoding (GSM-7 or UCS-2), segment count and the code found in it.

  2. 02

    Delivery steps per number

    Recipients decide what happens: delivered after 3 s, not delivered with a reason, never delivered, or a reply after a delay.

  3. 03

    The person texts back

    reply_sms_as_user sends Zenvia's MESSAGE webhook to the app. STOP-like words opt the number out; START opts it back in.

  4. 04

    Opt-outs enforced

    A send to an opted-out number gets 400 VALIDATION_ERROR, as Zenvia answers. Add or remove numbers by hand too.

  5. 05

    Status callbacks on demand

    Move a text to SENT, DELIVERED or NOT_DELIVERED with a reason, or send the same callback again to test duplicates.

  6. 06

    Callbacks with your answers

    Every MESSAGE_STATUS and MESSAGE callback is kept with the status your app returned; retry the ones it did not take.

  7. 07

    Limits like the gateway

    Over the throughput limit gets 429; over max segments gets 400 "message too long". Strict senders and templates refuse unknown ids.

  8. 08

    Wait for the code

    wait_for_sms blocks until the app texts a number and returns the OTP it found, so a sign-in test needs no phone.

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.

Every text, with what the app saw

Every text, with what the app saw: the SMS screen in Stuntman
1Opted out

The person texted STOP; the next send to this number is refused 400, as Zenvia does.

1 of 5
2Code extracted

The OTP is pulled out of the text; wait_for_sms returns it to the test.

2 of 5
3Encoding and segments

GSM-7 or UCS-2, characters per segment and the segment count billing would use.

3 of 5
4Status, as the app saw it

Accepted, SENT, DELIVERED: each callback with the status your app answered.

4 of 5
5Provoke on this message

Not delivered with a reason, or the same DELIVERED callback again.

5 of 5
  1. Opted out

    The person texted STOP; the next send to this number is refused 400, as Zenvia does.

  2. Code extracted

    The OTP is pulled out of the text; wait_for_sms returns it to the test.

  3. Encoding and segments

    GSM-7 or UCS-2, characters per segment and the segment count billing would use.

  4. Status, as the app saw it

    Accepted, SENT, DELIVERED: each callback with the status your app answered.

  5. Provoke on this message

    Not delivered with a reason, or the same DELIVERED callback again.

The simulated people behind numbers

The simulated people behind numbers: the SMS screen in Stuntman
1Pattern match

A number pattern with a trailing *: phone off, the text expires after 48 h.

1 of 5
2Delivered after

Each text is delivered after the wait you set, and the status callback follows.

2 of 5
3Answer a question

When the text asks something, the person replies with this text after 30 s.

3 of 5
4Nth text

On the third text in a day the person replies STOP and opts out.

4 of 5
5Saved as YAML

Recipients live in sms/recipients.yaml; first match wins, * is everyone else.

5 of 5
  1. Pattern match

    A number pattern with a trailing *: phone off, the text expires after 48 h.

  2. Delivered after

    Each text is delivered after the wait you set, and the status callback follows.

  3. Answer a question

    When the text asks something, the person replies with this text after 30 s.

  4. Nth text

    On the third text in a day the person replies STOP and opts out.

  5. Saved as YAML

    Recipients live in sms/recipients.yaml; first match wins, * is everyone else.

Senders, callbacks, opt-out and limits

Senders, callbacks, opt-out and limits: the SMS screen in Stuntman
1Senders

Alphanumeric, short code and long number; with strict_senders an unknown from gets 400.

1 of 5
2Callbacks to the app

Where MESSAGE_STATUS and MESSAGE (replies) are posted.

2 of 5
3Opt-out keywords

STOP, CANCEL, UNSUBSCRIBE opt out; START opts back in. Numbers on the list are shown.

3 of 5
4Throughput

Messages a second before the gateway answers 429.

4 of 5
5Body size

More segments than this gets 400 "message too long".

5 of 5
  1. Senders

    Alphanumeric, short code and long number; with strict_senders an unknown from gets 400.

  2. Callbacks to the app

    Where MESSAGE_STATUS and MESSAGE (replies) are posted.

  3. Opt-out keywords

    STOP, CANCEL, UNSUBSCRIBE opt out; START opts back in. Numbers on the list are shown.

  4. Throughput

    Messages a second before the gateway answers 429.

  5. Body size

    More segments than this gets 400 "message too long".

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

    Zenvia's INTERNAL_ERROR body; count sets how many sends fail

    force_sms_failure {answer: 500}
  • 400 validation error

    A VALIDATION_ERROR body, as Zenvia sends for bad input

    force_sms_failure {answer: 400}
  • Broken connection

    The connection resets, answers nothing, or hangs

    force_sms_failure reset | empty | timeout
  • Not delivered

    invalid, carrier_rejected, phone_off, blocked or not_covered

    set_sms_status NOT_DELIVERED
  • Never delivered

    The text stays SENT and expires after 48 h

    set_sms_recipient steps never_delivered
  • Duplicate callback

    The same MESSAGE_STATUS arrives again

    resend_sms_status
  • The person texts STOP

    The number opts out; the next send is refused 400

    reply_sms_as_user {text: STOP}
  • Rate limit

    Sends over the messages-a-second limit get 429

    set_sms_service limits.throughput
  • Message too long

    More segments than allowed gets 400

    set_sms_service limits.max_segments

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

Check that our app stops texting a customer after they reply STOP.

reply_sms_as_user{"number": "+1 646 555 0187", "text": "STOP"}
→ ok MESSAGE webhook sent, acme-api answered 200; number opted out
list_sms{"number": "+1 646 555 0187"}
→ ok next reminder refused 400 VALIDATION_ERROR: opted out (texted STOP)

MCP tools

  • list_smsEvery text both ways, with status history and the code found
  • wait_for_smsWait for the app to text a number; returns the OTP
  • reply_sms_as_userThe person texts back; STOP opts out
  • set_sms_statusMove a text to SENT, DELIVERED or NOT_DELIVERED
  • resend_sms_statusSend the same status callback again
  • force_sms_failureThe next sends fail: 500, 400, reset, empty, timeout
  • set_sms_recipientSteps for a number: delays, refusals, replies
  • list_sms_callbacksCallbacks sent to the app, with its answers

The same over HTTP

  • GET/api/sms/messages
  • GET/api/sms/wait
  • POST/api/sms/numbers/{number}/reply
  • POST/api/sms/force
  • PUT/api/sms/recipients