Voice API/Endpoint reference
Swagger UIOpenAPI

Endpoint reference

Receive signed inbound Twilio calls.

Use this endpoint as the Twilio Voice webhook for inbound calls so StateSet can resolve tenant routing, return TwiML, and open the realtime media stream.

Request API keyStart buildingEndpoint guidesAuthenticationProduction readiness
Runtime APIBearer tenant keys
Admin APIx-admin-key
TelephonyTwilio signatures
SpecsOpenAPI 3.1

Endpoint contract

PropertyValue
MethodPOST
Path/api/v1/incoming-call
AuthenticationX-Twilio-Signature
Content typeapplication/x-www-form-urlencoded
Primary useReceive inbound Twilio Voice callbacks and return TwiML for realtime media setup.

Twilio configuration

Twilio fieldProduction value
Voice webhook URLhttps://voice.stateset.app/api/v1/incoming-call
HTTP methodPOST
Signature headerX-Twilio-Signature
Fallback URLUse a human transfer, safe message, or callback workflow if the runtime is unavailable.

Example callback

POST /api/v1/incoming-call
X-Twilio-Signature: ${TWILIO_SIGNATURE}
content-type: application/x-www-form-urlencoded

From=%2B15555555678&To=%2B15555551234&CallSid=CA1234567890abcdef1234567890abcdef

Response behavior

The endpoint resolves the tenant and phone route, validates the Twilio signature when tenant configuration is available, and returns TwiML that connects the call to the realtime media stream.

<Response>
  <Connect>
    <Stream url="wss://voice.stateset.app/media-stream?stream_token=..." />
  </Connect>
</Response>

Validation flow

  1. Preserve the exact public URL Twilio used to generate the signature.
  2. Validate X-Twilio-Signature before trusting caller or route fields.
  3. Resolve tenant context from the called number or configured route.
  4. Create a short-lived media stream token and return TwiML.
  5. Record the inbound attempt for call logs, sessions, and downstream webhook events.

Failure modes

ScenarioExpected handling
Invalid signatureReject the callback and alert if repeated failures appear for a production phone route.
Unknown phone routeReturn safe fallback behavior and create an operator diagnostic event.
Media stream setup unavailableUse configured fallback routing rather than leaving the caller silent.
Provider retryProcess idempotently by call SID and route context.