> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Twilio

> Test SMS, voice calls, Verify codes and phone lookups with Twilio's API shapes and fictional phone numbers.

The Twilio tool covers 20 endpoints across REST 2010-04-01, Verify v2 and Lookup v2. Its key is `twilio`. Messages and calls stay in the world: nothing reaches a real phone.

## Connect

| Variable | Value |
| - | - |
| `TWILIO_API_URL` | Base URL. Append REST paths directly, `/verify` for Verify or `/lookups` for Lookup. |
| `TWILIO_ACCOUNT_SID` | Fictional account SID. Use it as the HTTP Basic username. |
| `TWILIO_AUTH_TOKEN` | Fake auth token. Use it as the HTTP Basic password. |

```ts TypeScript theme={null}
import twilio from 'twilio';
class Replica extends twilio.RequestClient {
  request(opts: any) {
    const url = new URL(opts.uri), host = url.hostname.split('.')[0];
    return super.request({ ...opts, uri: process.env.TWILIO_API_URL + (host === 'api' ? '' : '/' + host) + url.pathname + url.search });
  }
}
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN, { httpClient: new Replica() });
const messages = await client.messages.list({ limit: 20 });
```

This is what `ancha connect twilio --lang ts` prints. The SDK uses three Twilio hosts. Its custom `httpClient` sends each host to the corresponding path under `TWILIO_API_URL`.

For direct HTTP calls, send POST bodies as `application/x-www-form-urlencoded`. REST 2010-04-01 paths must end in `.json`.

## Endpoints

All 20 endpoints are partial. `ancha twins coverage twilio` prints the same paths and their limits.

| Method | Path | Support |
| - | - | - |
| `GET` | `/2010-04-01/Accounts/{AccountSid}.json` | partial |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/Balance.json` | partial: the seeded credit less what messages and calls cost |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json` | partial: PhoneNumber and FriendlyName filters |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json` | partial |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | partial: To, From and DateSent filters; newest first; PageSize, Page and PageToken pages with next\_page\_uri |
| `POST` | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | partial: SMS from the account’s numbers: queued, sent, then delivered, or undelivered to landlines and unreachable phones; opted-out recipients refused (21610). Nothing is sent and status callbacks are recorded, not called |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json` | partial |
| `POST` | `/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json` | partial: Body="" redacts a finished message |
| `DELETE` | `/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json` | partial |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | partial: To, From, Status and StartTime filters; PageSize, Page and PageToken pages with next\_page\_uri |
| `POST` | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | partial: Twiml or Url (recorded, never fetched): queued, ringing, in progress for the `<Say>` text, then completed; unreachable phones do not answer |
| `GET` | `/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json` | partial |
| `POST` | `/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json` | partial: Status=completed hangs up, Status=canceled cancels a call not yet answered, Twiml or Url replaces the instructions |
| `GET` | `/verify/v2/Services` | partial |
| `GET` | `/verify/v2/Services/{Sid}` | partial |
| `POST` | `/verify/v2/Services/{Sid}/Verifications` | partial: SMS and voice codes appear in the final world state; a pending verification is resent, up to five times; ten minutes to check |
| `GET` | `/verify/v2/Services/{Sid}/Verifications/{VerificationSid}` | partial |
| `POST` | `/verify/v2/Services/{Sid}/Verifications/{VerificationSid}` | partial |
| `POST` | `/verify/v2/Services/{Sid}/VerificationCheck` | partial: five wrong codes end the verification |
| `GET` | `/lookups/v2/PhoneNumbers/{PhoneNumber}` | partial: validation, line\_type\_intelligence and caller\_name from the world’s directory |

Unknown routes return HTTP 404 with Twilio's error shape and `x-ancha-gap: 1`.

## Starter data

The starter data is Acme's account, with a balance of 250.

| Record | Detail |
| - | - |
| Phone numbers | `+14155550100`, Acme Support, supports SMS and voice. `+14155550123`, Acme Alerts, supports SMS only. |
| Directory | Nine numbers: Greg Wilson, Rachel Moore, Victor Lane, Tom Hughes, Erin Walsh, Carla Diaz, Nora Bell, Megan Shaw and Helix Manufacturing. Megan has opted out. Helix is an unreachable landline. |
| Messages | Eight: Megan's opt-out exchange, an invoice reminder to Helix, three incident alerts, a dashboard update to Carla, and Erin's request for help finding a CSV export. |
| Calls | A completed call to Carla and a missed inbound call from Erin, 40 minutes before start. |
| Verify | Acme Login, with six-digit codes and a canceled verification for Tom. |

Run `ancha twins seed twilio --full` to print the complete starter data and the scene seed fields.

## Checks

Twilio has no state checks. Use [trace checks](https://docs.ancha.io/concepts/checks.md#trace-patterns), for example `{ called: "POST /2010-04-01/Accounts/*/Messages.json" }` or `{ not_called: "POST /2010-04-01/Accounts/*/Calls.json" }`.

## Limits

* SMS status follows the scene clock and the phone directory. Landlines and unreachable phones become undelivered; opted-out numbers are refused with error `21610`.
* Calls play no audio. Call URLs and status callbacks are recorded, never fetched or called.
* Verify codes appear in the final world state. A verification allows five sends and five wrong codes, and expires after ten minutes.
* MMS, WhatsApp, Messaging Services, Conversations, Studio and recordings are gaps. Authentication uses the account SID and auth token; API keys are a gap.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [ancha init](https://docs.ancha.io/cli/init.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.