Twilio Voice

In code

Declare the connector in connectors/*.yaml. The deploy looks phone_number up among the voice-capable numbers of the Connection's account, and activation links the agent, which needs voice_config in that deployment. Quote every phone number; unquoted, YAML reads it as an integer and the deploy fails.

type: twilio
connection: support-twilio
config:
  phone_number: "+4930123456"
  transfer_numbers:
    - "+4930123456789"
  allowed_callers:
    - "+4915112345678"
  fallback_number: "+4930987654321"
  max_wait_seconds: 60
  hold_audio_path: assets/hold.mp3
agents:
  - support-voice

Connection

A Twilio Connection holds the account credentials and can serve any number of Twilio Voice and Twilio Messaging connectors in the same account and region. connic uses the Account SID and Auth Token to check the account, list numbers, and set webhooks. The Auth Token also verifies the signature of every request Twilio sends.

Generated values

connic creates this value when the connector is created and keeps it across updates and deploys. Leave it out of YAML files; connic lint rejects it.

Outgoing calls

In outbound mode, every run of the linked agent is a call. In the agent's Connector Flow, click Add outbound connector, select Twilio Voice, and choose Outgoing calls as the mode. Start the runs any way you like, for example from a webhook connector, or from another agent with trigger_agent.

When a run starts, connic calls the number in the input's to field from the connector's number, or the connector's default number when the input has none. With a greeting, the agent speaks first once someone answers; without one, it waits for them to speak. It knows about the call what the run input tells it. The agent gets through phone menus with press_keys and can wait on hold until a person answers. Runs beyond the agent's max_concurrent_runs wait before connic dials, so nobody who answers has to wait for the agent. The agent can transfer the call to a transfer number, like an incoming call.

The run fails when nobody answers within the ring time, the line is busy, or the call can't be connected, and its error says which. If a mailbox answers, the agent hears its greeting like a person, so tell the agent in its system prompt what to do then, for example leave a short message after the tone and hang up.

type: twilio
mode: outbound
connection: support-twilio
config:
  phone_number: "+4930123456"
  ring_seconds: 40
agents:
  - reminder-calls

{
  "to": "+4915112345678",
  "customer": "Alex Example",
  "reason": "Confirm tomorrow's appointment at 10:00"
}

Allowed callers

With allowed callers, connic turns away calls from all other numbers and from hidden numbers before Twilio answers them, so they start no run. The connector logs show each rejected call and its number. Caller numbers can be faked, so don't rely on this list alone to protect sensitive data.

Waiting callers

Every call is a run, so the agent takes as many calls at once as its max_concurrent_runs allows. Further callers wait in line and reach the agent in the order they called. While they wait, they hear the ringing tone or the connector's hold audio. A caller still waiting after the maximum wait goes to the fallback number; without one, the call ends and its run fails.

If the hold audio file is missing or can't be played, waiting callers hear the ringing tone and the connector logs show why. A changed file plays once it's deployed.

Transfers and fallback

When an agent tool raises TransferCall with one of the connector's transfer numbers, Twilio dials that number. If nobody answers there, the call ends. If an accepted incoming call can't continue, for example because the run fails or the caller waited the maximum wait, Twilio dials the fallback number instead. Without a fallback number, the call ends. The fallback number applies only in sync mode and not to transfers.

Calls connic doesn't accept, for example while the connector is paused or the environment has no active deployment, go to the number's Primary handler fails setting in Twilio, which connic leaves unchanged. Point it at TwiML that dials a staff number to forward those calls too.