Signals Docs
Moving from Twilio

Moving from Twilio

The Calls API follows Twilio's 2010-04-01 Calls and Recordings resources, and OneML is compatible with TwiML, so most Twilio voice integrations run on Signals after you change the base URL and credentials. This page names Twilio and TwiML directly. It lists what you change, what Signals serves, and where behaviour differs.

What you change

TwilioSignals
Base URLhttps://api.twilio.comhttps://api.signals.pressone.africa
Path/2010-04-01/Accounts/{AccountSid}/...Same
UsernameAccount SID, or an API key SID (SK...)Voice Account AccountSid only. It must equal the AccountSid in the path.
PasswordAuth token, or API key secretVoice Account auth token
To on create-callA phone number, a client, or a SIP addressAn E.164 number with a leading +, or sip:user@domain for a SIP user registered on your own Signals SIP domain.
Webhook signature keyAuth tokenVoice Account auth token. X-Twilio-Signature is computed as on Twilio. See Request signatures.
Inbound call setupPhone number voice URL, or a TwiML AppA voice application, with a number routed to it. See Receiving calls.

Configure your HTTP client, or your helper library's HTTP layer, to send requests to api.signals.pressone.africa. Find the AccountSid and auth token in the Signals console under Developers, Voice Account.

Resources Signals serves

ResourceMethodsNotes
Calls.jsonGET, POSTList and create calls.
Calls/{CallSid} (.json optional)GET, POST, DELETEFetch, update and delete a call. PATCH is not accepted.
Calls/{CallSid}/Recordings.jsonGETList a call's recordings.
Calls/{CallSid}/Recordings/{RecordingSid} (.json optional)GET, DELETEFetch and delete one of the call's recordings. A recording of another call returns 404.
Calls/{CallSid}/Events.jsonGETThe requests Signals made to your URLs during the call, with your responses. See Inspect requests with call events.
Recordings.jsonGETList the account's recordings.
Recordings/{RecordingSid} (.json optional)GET, DELETEFetch and delete a recording.
Recordings/{RecordingSid}.wavGET, HEADRecording audio. .mp3 and other formats are not served.

Every other Twilio resource, such as Messages, IncomingPhoneNumbers, Applications, Conferences or Queues, returns 404 with code 20404. A method that a served resource does not accept returns 405 with code 20004. Manage numbers and voice applications through the Signals API instead.

Supported verbs

Each OneML verb links to its reference page.

OneML verbTwiML verbNotes
Say<Say>Voice and language handling differ. See Behaviour differences.
Play<Play>
Gather<Gather>
Record<Record>
Dial<Dial>Bare numbers and <Number> children only.
Redirect<Redirect>
Pause<Pause>
Hangup<Hangup>
Reject<Reject>
Stream<Connect><Stream>Two-way, blocking media session.
Stream<Start><Stream>, <Stop><Stream>One-way, non-blocking media session.
DisconnectNoneOneML extension.

Not supported

The elements and attributes below are not implemented. They fail in different ways: some reject the document, others are skipped, and others are accepted with no effect. A rejected document is visible at once; a skipped element is not, so check your documents for these before you move.

Rejected with a validation error

VerbWhat happens
<Pay>Fails validation with <Pay> is not supported yet. Inline Twiml containing <Pay> is refused when you send it: create-call and update-call return 400 with code 12100, and no call is placed or redirected. A <Pay> in a document fetched from your URL or a <Redirect> target fails when Signals runs it, and the call ends as failed, as shown on the call resource or in a status callback.

Accepted and skipped

These elements pass validation, but nothing runs them. Signals moves on to the next verb with no error, no action request and no signal to your server or the caller.

ElementContextNotes
<Enqueue>Child of <Response>
<Leave>Child of <Response>
<Refer>Child of <Response>Its sendDigits format is checked, but the verb never runs.
<Siprec>Child of <Start> or <Stop>
<Transcription>Child of <Start> or <Stop>
<ConversationRelay>Child of <Connect>Only <Connect><Stream> is implemented.
<Room>Child of <Connect>
<VirtualAgent>Child of <Connect>

<Start> and <Stop> still need at least one recognized child (<Siprec>, <Stream> or <Transcription>) to pass validation. An empty <Start> or <Stop> is rejected. Only the <Stream> child runs.

Dial targets that are dropped

<Dial> dials bare phone numbers and <Number> children. The following targets parse without error but are dropped when Signals builds the list of numbers to dial. If a <Dial> contains only these targets, Signals reports a failed dial to its action URL when one is set.

TargetNotes
<Conference>
<Client>
<Queue>
<Application>
<Sip>Not available for Programmable Voice. To reach your own PBX, dial a Signals number that is routed to your SIP trunk; Signals connects it on net.

Dial attributes that are ignored

These <Dial> attributes are validated but have no effect.

AttributeNotes
trimRecording trim is not configurable through <Dial>.
referUrl
recordingTrack

REST API differences

  • The Basic username must be the path AccountSid. Signals rejects any other username with 401 and code 20003 before the request goes further. Twilio API key SIDs (SK...) and parent-account credentials on a subaccount path are not accepted.
  • SIDs are lowercase. AccountSid, CallSid and RecordingSid must be two uppercase letters followed by 32 lowercase hexadecimal characters. Any other form returns 404.
  • From and CallerId must be numbers your project holds. Both are E.164 numbers with a leading +, such as +2342013300100. Create-call refuses a number your project does not hold with error 21210, and a From that is not E.164 with error 21212.
  • To reaches your own SIP users. Besides an E.164 number, To accepts sip:user@domain when the domain is your own Signals SIP domain and the user is registered on it. Another domain, or a user that is not registered, returns error 21214. A SIP address with a port, parameters or headers, or a sips: address, returns error 21211.
  • Byoc takes a Signals carrier connection. As on Twilio, Byoc names the connection the call leaves through, here a byo_ ID such as byo_01a19b7e-deee-779d-953d-a3f8be2d1617. It must be the connection of the From number, which already decides the route, so you rarely need it. Another connection fails the call. A value that is not a connection ID or default, or a Byoc with a sip: To, returns error 20001. See Bring your own carrier.
  • Recording is a create-call parameter; machine detection is not. Record, RecordingChannels (mono or dual), RecordingTrack (inbound, outbound or both), RecordingStatusCallback, RecordingStatusCallbackMethod (GET or POST) and RecordingStatusCallbackEvent (in-progress, completed or absent, repeatable) are supported, and the recording appears with source OutboundAPI. Values are not case sensitive, and RecordingStatusCallbackEvent accepts several events separated by spaces, as Twilio documents. The Recording* fields apply only when Record is true and are ignored otherwise. Method, FallbackMethod and StatusCallbackMethod must also be GET or POST. A value outside these sets returns error 20001, and a RecordingStatusCallback that is not an absolute http(s) URL returns 21205. MachineDetection, MachineDetectionTimeout and Trim are refused with error 20001, naming the parameter. The RecordingSid in the first recording callback already resolves on GET Recordings/{RecordingSid}: the recording reads in-progress while it is captured, processing while it is checked, and then completed or absent. Recording callbacks carry RecordingStartTime once recording has started, and an absent callback carries ErrorCode when Signals knows why nothing was recorded (see Recording error codes). A recording cannot be paused, resumed or stopped while the call runs: there is no Calls/{CallSid}/Recordings create or update.
  • ApplicationSid is rejected. Create-call fails with error 21605 when ApplicationSid is present. Use Url or Twiml. A Signals voice application ID is not accepted there either; voice applications serve inbound numbers.
  • A project needs a billing account to place calls. Without one, create-call returns 403 with code 20005 and the call is not placed.
  • Inbound numbers point at voice applications. A Signals number has no voice URL of its own. Create a voice application and route the number to it.
  • Timeout defaults to 60 seconds on create-call, the same as Twilio.
  • Empty and repeated fields. A form field with an empty value counts as absent, and when a field is repeated only its first value counts, except StatusCallbackEvent and RecordingStatusCallbackEvent. Fields an operation does not list are ignored, as on Twilio.
  • A new call can already be ringing. Create-call returns the call as Signals records it. That is usually queued, but it can already be ringing when the call's first progress event arrived first.
  • Call updates use form fields. Send POST with the fields as a form. Url or Twiml redirects an in-progress call, and the voice platform refuses a redirect before answer with error 21220. Status=completed ends a queued, ringing or in-progress call. Status=canceled ends only a queued or ringing call: on an answered call Signals refuses it with error 21220, where Twilio ignores it, so send Status=completed instead. Status cannot be combined with Url, Method or Twiml.
  • Updates can change call parameters. FallbackUrl, FallbackMethod, StatusCallback, StatusCallbackMethod and TimeLimit may be sent alone or with a redirect or a status. TimeLimit counts from answer, so it is not applied to a call that has not been answered; a limit the call has already passed returns error 13216. A call that has ended accepts no update (21220), and a body with none of these fields is refused with 21220 too.
  • An update answers with the call as Signals records it. The 200 response can still show the status from before the update until the voice platform reports the change.
  • DELETE deletes the call record. It does not hang up. A call that has not ended returns 400 with code 20009. After the delete, fetching or updating the call returns 404, it is no longer listed, and its Events.json returns 404. Its recordings are kept and can still be listed, fetched, downloaded and deleted.
  • Lists are paginated with Page and PageSize. PageSize defaults to 50 and accepts 1 to 1,000. Only the PascalCase names are recognized, and there is no PageToken: follow next_page_uri, which repeats your filters.
  • The Calls resource holds Programmable Voice calls only. A call an Automation placed is not listed, and fetching or deleting it returns 404 with code 20404.
  • Call list filters. Calls.json filters by Status, To, From, ParentCallSid, and StartTime or EndTime with =, < or >. An unknown Status returns error 20001. StartTime compares date_created, the time Signals first recorded the call. EndTime compares end_time. A date value is a UTC day, as on Twilio: StartTime=2026-10-26 matches calls created on 26 October, StartTime>2026-10-26 matches calls created on or after 26 October, and StartTime<2026-10-26 matches calls created before 26 October. With an instant, < matches times strictly before it, > matches times at or after it, and = matches the whole UTC day the instant falls on: StartTime=2026-10-26T09:00:00Z matches every call created on 26 October. Twilio's StartTime>= and StartTime<= spellings are the same > and < filters, because the = separates the name from the value.
  • Recording list filters. Recordings.json and Calls/{CallSid}/Recordings.json filter by DateCreated with =, < or >, with the same date and instant rules as StartTime. The account-wide list also filters by CallSid, and both accept IncludeSoftDeleted. A CallSid your account does not know lists no recordings.
  • Deleted recordings stay visible on request. DELETE Recordings/{RecordingSid} and DELETE Calls/{CallSid}/Recordings/{RecordingSid} return 204, and so does a repeat. The recording is then hidden unless you send IncludeSoftDeleted=true, which shows it with status deleted. A recording still being processed, or under a legal hold, returns 400 with code 20009.
  • Recording audio needs authentication. RecordingUrl and the .wav resource require your AccountSid and auth token. Recording metadata carries no media_url. Audio that is not ready yet returns 404, as on Twilio. See Download recording audio.
  • price is the connectivity charge. A call's price is negative, as on Twilio, in the currency in price_unit, and stays null until every charge on the call has been rated.
  • Call resources link to their events. Call responses include subresource_uris.events, pointing at Calls/{CallSid}/Events.json.
  • Request bodies are limited to 1 MiB. A larger body returns 413 with code 20001.
  • Timeouts return 504. Signals waits at most 10 seconds for the voice platform to confirm a new call and 15 seconds for it to apply an update.
  • Errors have one shape. Every error is Twilio-style JSON with code, message, status and more_info, whether Signals raised it or the voice platform did. The voice platform's refusals of a create or an update are returned unchanged.

Recording error codes

An absent recording callback and the absent Recordings resource carry one of these codes in ErrorCode and error_code when the recording could not start or its audio could not be kept. They are Signals codes, not Twilio's. A recording that is absent without a code ended before any audio was captured, or its stored audio failed Signals' own verification.

CodeMeaning
61001The call leg was gone when recording was to start.
61002The voice platform could not write the recording file.
61003The voice platform did not confirm the recording start in time.
61004The recorded audio was not a valid file, so it was not kept.

The call itself continues whatever the recording's outcome.

Behaviour differences

  • <Dial> works only inside an active call. As with Twilio, <Dial> does not start an outbound call. Create the call through the Calls API, then use <Dial> in its OneML.
  • <Dial> caller IDs depend on how the call started. On a call you created through the Calls API, callerId may be a number your project owns or any other E.164 number, written with a leading +, that is not another customer's number. On an inbound call, callerId must be a number your project owns. Without callerId, Signals uses From for calls created through the Calls API and To for inbound calls. It never presents an arbitrary incoming caller number as yours. Dialed numbers go through your project's outbound policy.
  • <Dial record> dual-channel modes record one mixed channel. The from-answer and from-ringing start points are honoured, but record-from-answer-dual and record-from-ringing-dual do not produce a channel per party.
  • <Say> uses Google Cloud Text-to-Speech, not Amazon Polly, including for the man, woman and alice aliases.
  • <Say voice> is not checked against a list. man (the default) and any unrecognized plain string select a Google male voice; woman and alice, in lowercase, select a Google female voice. See Voice selection.
  • <Say voice> accepts a provider prefix. Google.<voice-name> and Elevenlabs.<voice-id> select a specific Google Cloud Text-to-Speech or ElevenLabs voice.
  • <Say language> must match the voice. A mismatch returns a clear error. The built-in aliases support en and en-US. For another Google language, select a matching Google.<voice-name>. The current ElevenLabs integration accepts en and en-US.
  • <Number sendDigits> is accepted but not applied. Signals checks its format but does not send the tones.
  • <Connect> action and method are never requested. When a <Connect><Stream> session ends, the next verb runs.
  • <Start><Stream> metadata omits account_sid. <Connect><Stream> includes it. See Stream.
  • Inbound status callbacks come from the voice application. An inbound call sends a completed status callback only when its voice application has a status callback URL. API-created calls use StatusCallback as on Twilio. See Status callbacks.
  • StatusCallbackEvent is not validated. Any string is accepted; only initiated, ringing, answered and completed ever match an event.
  • The webhook user agent keeps its Twilio name. Requests carry User-Agent: TwilioProxy/1.1.

Next steps

Last modified on