Worlds / Comms and scheduling

Twilio API

A local Twilio account with phone numbers, messaging services, SMS and calls, opt-outs and delivery status callbacks. Test the agent that sends reminders and replies by text, and respects who opted out.

Base path: /2010-04-01/Accounts/{AccountSid}
Auth: Account SID and auth token over HTTP basic auth, the world key
Endpoints: 15
Status: Active today

This reference previews the surface the Twilio world serves in the closed beta. Paths mirror the public Twilio API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_TWILIO_URL`	This world's origin followed by `/2010-04-01/Accounts/{AccountSid}`
`WORLDS_API_KEY`	The world key, accepted wherever Twilio expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · twilio

import twilio from "twilio";

const client = twilio("ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", process.env.WORLDS_API_KEY);
client.api.baseUrl = process.env.WORLDS_TWILIO_URL;

const message = await client.messages.create({
  to: "+15558675310",
  from: "+15017122661",
  body: "Your order shipped",
});

API reference

15 of 15

Messages

SMS and MMS sent and received.

POST/2010-04-01/Accounts/{AccountSid}/Messages.jsonSend a message
GET/2010-04-01/Accounts/{AccountSid}/Messages.jsonList messages
GET/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.jsonFetch a message
POST/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.jsonUpdate or redact a message

Fields · 6

`sid`	string	Message SID
`to`	string	Recipient number
`from`	string	Sender number
`body`	string	Message text
`status`	string	queued, sent, delivered, failed and more
`date_sent`	datetime	Time sent

Calls

Voice calls placed and received.

POST/2010-04-01/Accounts/{AccountSid}/Calls.jsonCreate a call
GET/2010-04-01/Accounts/{AccountSid}/Calls.jsonList calls
GET/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.jsonFetch a call
POST/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.jsonUpdate or end a call

Fields · 5

`sid`	string	Call SID
`to`	string	Called number
`from`	string	Calling number
`status`	string	queued, ringing, in-progress, completed and more
`duration`	string	Length in seconds

Incoming phone numbers

Numbers on the account and their webhooks.

GET/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.jsonList numbers
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.jsonBuy a number
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.jsonUpdate a number
DELETE/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.jsonRelease a number

Fields · 5

`sid`	string	Number SID
`phone_number`	string	Number in E.164 format
`friendly_name`	string	Label
`sms_url`	string	Webhook for texts
`voice_url`	string	Webhook for calls

Recordings

Audio recordings of calls.

GET/2010-04-01/Accounts/{AccountSid}/Recordings.jsonList recordings
GET/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.jsonFetch a recording
DELETE/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.jsonDelete a recording

Fields · 4

`sid`	string	Recording SID
`call_sid`	string	Call it belongs to
`duration`	string	Length in seconds
`status`	string	in-progress, completed or absent

Test workflow

Prepare. Select the Twilio setup for your workflow and review its starting records, including messages, calls, incoming phone numbers.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

No messages to opted-out numbers
0142 reply sent from the number they texted
One reminder per patient, no duplicates
HELP reply sent to 0188
No calls placed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Twilio
version: 2
connector: twilio
seed: twilio-starter
mode: isolated
policy: >
  Send tomorrow's appointment reminders and answer reschedule requests. Skip
  anyone who has opted out, and reply from the number each patient texted.
tasks:
  - id: send-appointment-reminders-from-the-right-number
    prompt: Send appointment reminders from the right number
  - id: reply-to-inbound-texts-in-the-same-conversation
    prompt: Reply to inbound texts in the same conversation
  - id: honor-stop-and-help-keywords
    prompt: Honor STOP and HELP keywords
expected:
  - No messages to opted-out numbers
  - 0142 reply sent from the number they texted
  - "One reminder per patient, no duplicates"
  - HELP reply sent to 0188
  - No calls placed
scenarios:
  - opted-out
  - invalid-number
  - carrier-filtered

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`opted-out`	Sending to a STOP recipient returns error 21610
`invalid-number`	A bad To number returns error 21211
`carrier-filtered`	The message ends undelivered with 30007
`rate-limited`	The API returns 429 with error 20429
`callback-twice`	The delivered status callback arrives two times

Starting data

Start each run from the same records and relationships. The overview below describes the Twilio starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
numbers	3 long codes and 1 toll-free number on a messaging service
messages	800 messages, queued, sent, delivered, undelivered and failed
opt-outs	40 recipients who replied STOP
calls	Call logs with status and duration
status callbacks	Delivery callbacks for every message

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Messages records

Messages

SMS and MMS sent and received.

Field	Type	Meaning / relationship
`sid`	string	Message SID
`to`	string	Recipient number
`from`	string	Sender number
`body`	string	Message text
`status`	string	queued, sent, delivered, failed and more
`date_sent`	datetime	Time sent

json · illustrative record shape

{
  "sid": "<Message SID>",
  "to": "<Recipient number>",
  "from": "<Sender number>",
  "body": "<Message text>",
  "status": "<queued, sent, delivered, failed and more>",
  "date_sent": "<Time sent>"
}

See messages operations

Calls records

Calls

Voice calls placed and received.

Field	Type	Meaning / relationship
`sid`	string	Call SID
`to`	string	Called number
`from`	string	Calling number
`status`	string	queued, ringing, in-progress, completed and more
`duration`	string	Length in seconds

json · illustrative record shape

{
  "sid": "<Call SID>",
  "to": "<Called number>",
  "from": "<Calling number>",
  "status": "<queued, ringing, in-progress, completed and more>",
  "duration": "<Length in seconds>"
}

See calls operations

Incoming phone numbers records

Incoming phone numbers

Numbers on the account and their webhooks.

Field	Type	Meaning / relationship
`sid`	string	Number SID
`phone_number`	string	Number in E.164 format
`friendly_name`	string	Label
`sms_url`	string	Webhook for texts
`voice_url`	string	Webhook for calls

json · illustrative record shape

{
  "sid": "<Number SID>",
  "phone_number": "<Number in E.164 format>",
  "friendly_name": "<Label>",
  "sms_url": "<Webhook for texts>",
  "voice_url": "<Webhook for calls>"
}

See incoming phone numbers operations

Recordings records

Recordings

Audio recordings of calls.

Field	Type	Meaning / relationship
`sid`	string	Recording SID
`call_sid`	string	Call it belongs to
`duration`	string	Length in seconds
`status`	string	in-progress, completed or absent

json · illustrative record shape

{
  "sid": "<Recording SID>",
  "call_sid": "<Call it belongs to>",
  "duration": "<Length in seconds>",
  "status": "<in-progress, completed or absent>"
}

See recordings operations

See the Twilio world in the catalog