Twilio Voice Channel

Overview

Toggle int-twilio-channel on a useragent and Wiro auto-enables the bundled voice rules (util-voice-receptionist + util-voice-call-prep) via the registry's depends_on chain — you don't need to enable them separately.

Skills that use this credential:

• int-twilio-channel — Twilio Voice channel.

Agents that typically enable this integration:

• Voice Receptionist (phone-receptionist for SMBs)
• Custom agents that handle inbound calls

Availability

Webhook auto-configuration

You don't touch the Twilio Console's webhook fields manually — when you save this credential through POST /UserAgent/CredentialUpsert (or the panel), Wiro uses your Account SID + Auth Token to auto-configure each phone number's VoiceUrl and StatusCallback. No separate "Setup webhooks" step.

Prerequisites

• A Wiro API key — Authentication.
• A deployed agent (Voice Receptionist preset or any custom agent with int-twilio-channel enabled) — Agent Overview.
• A Twilio account with at least one purchased phone number.

Setup

Step 1: Get your Twilio Live Credentials

1. Twilio Console → Account → Keys & Credentials → API keys & tokens.
2. In the Live credentials section at the top of the page, copy:
   • Account SID — 34 chars, starts with AC.
   • Auth Token — click Show to reveal. 32-char secret.

Step 2: Buy or import phone numbers

Twilio Console → Phone Numbers → Active numbers → Buy a number. Pick a number with Voice capability (toll-free, local, or international as desired).

Numbers must be in E.164 format when you save them to Wiro:

• Starts with +
• Country code first (no leading 0)
• Digits only — no spaces, dashes, or parentheses
• Max 15 digits total

Examples: +14155551234 (US), +447911123456 (UK), +905551234567 (Turkey), +5511955256325 (Brazil).

Step 3: Save credentials to Wiro

curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "fields": [
      { "credentialkey": "twilio-voice", "fieldname": "accountsid",      "fieldvalue": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
      { "credentialkey": "twilio-voice", "fieldname": "authtoken",       "fieldvalue": "your-32-character-auth-token" },
      { "credentialkey": "twilio-voice", "parentfield": "phonenumbers", "ordinal": 0, "fieldname": "value", "fieldvalue": "+14155551234" },
      { "credentialkey": "twilio-voice", "fieldname": "maxcallseconds",  "fieldvalue": "600" },
      { "credentialkey": "twilio-voice", "fieldname": "holdstrategy",    "fieldvalue": "text_then_music" },
      { "credentialkey": "twilio-voice", "fieldname": "holdtext",        "fieldvalue": "Please hold while we connect you to our assistant." },
      { "credentialkey": "twilio-voice", "fieldname": "holdvoice",       "fieldvalue": "Polly.Joanna-Neural" }
    ]
  }'

Or save through the panel: My Agents → open agent → Credentials → Twilio Voice. The panel form auto-validates Account SID format and runs Setup webhooks on save.

Step 4: Verify webhook configuration

After saving credentials, the response includes:

• twilioWebhooksUpdated — numbers whose VoiceUrl was successfully written.
• twilioWebhookSkipped — a single reason string, returned instead of twilioWebhooksUpdated when the VoiceUrl step was skipped (e.g. no matching IncomingPhoneNumber on Twilio account).
• twilioWebhooksFailed — Twilio API errors per number, if any.
• twilioWebhookError — present instead of the three fields above when the entire auto-webhook flow throws (e.g. Twilio API outage, invalid Account SID format, network error). Holds a single error string. Treat as "no numbers were configured this round; retry the save".

You can also confirm in the Twilio Console: open the number → Voice Configuration → A call comes in should show:

• Configure with → Webhook, TwiML Bin, Function, Studio Flow, Proxy Service
• Webhook URL → a Wiro voice handler URL
• HTTP → POST

Step 5: Start the agent and place a test call

curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "your-useragent-guid" }'

Once the agent is in status 4 (running), dial your Twilio number from any phone. You should hear the configured hold experience for ~5–8 seconds, then the agent's greeting.

Credential Fields

Credentials schema (as returned by POST /UserAgent/Detail)

"twilio-voice": {
  "_connected": true,
  "optional": false,
  "extra": false,
  "accountsid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "authtoken": "***encrypted***",
  "phonenumbers": ["+14155551234"],
  "maxcallseconds": 600,
  "whitelistedcallers": [],
  "holdstrategy": "text_then_music",
  "holdtext": "Please hold while we connect you to our assistant.",
  "holdvoice": "Polly.Joanna-Neural",
  "holdaudio": null,
  "holdmusic": "https://cdn.wiro.ai/uploads/.../music.mp3"
}

Call History

Retrieve the last N realtime voice sessions for a useragent — regardless of which channel they came in on.

POST /UserAgent/TwilioCallHistory/List

curl -X POST "https://api.wiro.ai/v1/UserAgent/TwilioCallHistory/List" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "limit": 50
  }'

Response:

{
  "result": true,
  "errors": [],
  "data": [
    {
      "messageguid": "5c41dabf-f2be-4aa8-a5a4-8c9e3d2f3f11",
      "agenttoken": "8a5b9e2f-4d3c-4a01-9c2e-1b6d4e7a9c5d",
      "channel": "twilio",
      "callsid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "callerInfo": { "number": "+15551234567", "country": "US" },
      "callerProfile": "Returning caller — last asked about pricing.",
      "status": "realtime_session",
      "endReason": "wiro_completed",
      "durationSeconds": 137,
      "modelSlug": "gpt-realtime-mini",
      "startedAt": 1730473321000,
      "endedAt":   1730473458000
    },
    {
      "messageguid": "0f2a1c3d-9e8b-4c5a-bf42-3a7b6e1d0c8f",
      "agenttoken": "1e7d3b9a-5c2f-4d6b-8e0a-2f4c7b5d9e1a",
      "channel": "web",
      "callsid": "voice-call-9d2d4b6e3f6b4c1a8a7e1f5a0b2c3d4e",
      "callerInfo": { "page_url": "https://example.com/contact", "display_identifier": "+15551234567" },
      "callerProfile": null,
      "status": "realtime_session",
      "endReason": "browser_disconnect",
      "durationSeconds": 42,
      "modelSlug": "gpt-realtime-mini",
      "startedAt": 1730463668000,
      "endedAt":   1730463710000
    }
  ]
}

Pairing With Other Skills

Pair this channel with skills that supply the conversation behavior:

• int-google-calendar — read availability + draft appointments during the call.
• int-hubspot-crm — match caller phone number against CRM contacts and log call outcomes.
• int-brevo-email / int-sendgrid-email / int-mailchimp-email — draft post-call confirmation or follow-up emails.

The Voice Receptionist preset bundles this channel together with the voice rules and Brevo/HubSpot credentials by default — see Agent Use Cases for the full preset.

Troubleshooting

• All calls fail with signature error: You probably pasted an API Key Secret instead of the live Auth Token. Re-paste from the Live credentials section of the Twilio Console.
• Number isn't in twilioWebhooksUpdated: The number isn't on the Twilio account whose Account SID you provided. Either buy the number on this account, or import it from the source account. The skip reason no matching IncomingPhoneNumber on Twilio account confirms this.
• Caller hears Twilio's default voicemail: The number's Configure with is set to TwiML App or SIP Trunk — flip it back to Webhook in the Twilio Console, then re-save credentials in Wiro to re-write VoiceUrl.
• Calls cut off at exactly N seconds: That's maxcallseconds. Raise it for longer use cases.
• Hold music plays forever, agent never speaks: The agent failed to start the realtime conversation. Check POST /UserAgent/Logs for errors.
• Caller hears your fallback message but no agent: maxcallseconds was reached before the agent connected, or the agent crashed mid-call. Check POST /UserAgent/Logs.
• Whitelisted caller still gets busy signal: Ensure E.164 format. Twilio normalizes inbound numbers — if your test phone presents itself as 4155551234 instead of +14155551234, the allowlist won't match. Add both forms while testing.
• Rotated the Auth Token in Twilio Console: Re-paste the new token in Wiro and save again — the credential save also re-runs the webhook setup.

Related

• Agent Credentials & OAuth
• Agent Skills — toggle skills on/off, configure preferences and crons
• Agent Use Cases — Voice Receptionist preset
• Web Voice — browser-embedded voice for the same agent, shares this page's Call History feed
• Google Calendar Skills — pair for inbound voice booking
• HubSpot Skills — caller identification + CRM logging
• Twilio Voice docs