Orbitali Docs

Inbound SIP API

Manage inbound SIP connections and numbers when the gateway is enabled.

These endpoints are available only when your Orbitali operator enables the SIP gateway. They use the same organization API key as the rest of the public API. Every route returns 404 when SIP is disabled. Read Inbound SIP for provider configuration and supported audio/transport settings.

Endpoints

MethodPathSuccess
GET/public/v1/telephony/sip/connections200, array of connections
POST/public/v1/telephony/sip/connections201, { connection, password? }
PUT/public/v1/telephony/sip/connections/{connection_id}200, { connection, password? }
POST/public/v1/telephony/sip/connections/{connection_id}/rotate200, { connection, password }
DELETE/public/v1/telephony/sip/connections/{connection_id}200, { id }
POST/public/v1/telephony/sip/numbers201, { id }

Create a connection

curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/connections \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayLabel": "Office inbound",
    "authMode": "credentials",
    "sourceCidrs": [],
    "enabled": true
  }'
FieldRequirement
displayLabelRequired, 1–80 characters
authModeRequired, credentials or ip
sourceCidrsDefaults to []; at most 32 IPv4 addresses/CIDRs. Must be empty for credentials, nonempty for IP authentication.
enabledDefaults to true
outboundOptional outbound route for handoff; omitted preserves an existing route, null removes it and its password.

Unknown input fields are rejected. For IP authentication, use authMode: "ip" and your provider's source ranges. Allowlists cannot overlap another connection, including disabled connections.

The response's connection contains id, displayLabel, authMode, sourceCidrs, enabled, username, destination, revision, provisioningStatus, verifiedAt, and outbound (without its password). Store the returned ID as SIP_CONNECTION_ID for later requests. Credential-mode passwords are returned only when generated; store the password securely and configure it at your provider.

List and check provisioning

curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/connections \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

Returns an array of connection objects without passwords. provisioningStatus is pending, applied, or failed. applied confirms gateway configuration loading; a non-null verifiedAt records a successful call verification. Test speech, interruption, and hangup after configuration changes.

Replace, disable, or rotate

To update a connection, PUT the complete connection input to /public/v1/telephony/sip/connections/{connection_id}. Include enabled: false to disable it. Changing authentication mode generates new credentials when switching to credential mode.

Rotate a credential-mode password without a request body:

curl --fail-with-body "https://api.orbitali.ai/public/v1/telephony/sip/connections/$SIP_CONNECTION_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

Store the returned password, update your provider, and wait for the new revision to be applied. IP-mode connections have no password to rotate.

Add and assign a number

curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/numbers \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "00000000-0000-4000-8000-000000000001",
    "phoneNumber": "+34910000001",
    "friendlyName": "Office"
  }'

Replace connectionId with your returned UUID and phoneNumber with your provider-routed E.164 number. Both fields are required; friendlyName is optional (1–80 characters). Success returns the new phone-number id. Assign it using Assign a phone number and activate the agent.

Routing requires the authenticated connection and called number together. Unknown or unassigned destinations are rejected before answering. SIP supports incoming calls and direct transfers through an explicitly configured outbound route. REGISTER, SIP extensions, attended transfers, and standalone outbound SIP calls are not supported.

Configure direct call transfers

Set the agent's existing E.164 handoff number, then include outbound in the connection's POST/PUT input:

{
  "displayLabel": "Office inbound",
  "authMode": "credentials",
  "sourceCidrs": [],
  "enabled": true,
  "outbound": {
    "host": "pbx.example.com",
    "port": 5060,
    "transport": "tcp",
    "username": "outbound-user",
    "password": "REPLACE_LOCALLY",
    "callerId": "+34910000002"
  }
}

host is a hostname or IPv4 address, without scheme, path or SIP user. port defaults to 5060 (1–65535); transport is udp (default) or tcp. callerId is a required E.164 number your PBX permits you to present. Original caller identity is not forwarded automatically. Leave username empty for an IP-authorized trunk. Otherwise provide separate outbound credentials; the inbound Orbitali credentials do not authorize calls through your PBX.

Usernames accept letters, digits and _.@+- (at most 128 characters). Passwords accept letters, digits and ._~!$%&*+/@=- (1–128 characters); configuration delimiters and line breaks are rejected. Passwords are encrypted at rest, are never returned by public reads, and are preserved when omitted on update. Sending outbound: null removes the outbound password. Rotating the inbound password preserves the outbound route and its independent password.

Wait for provisioningStatus: "applied", then place a new inbound call. The runtime enables transfer_call only for a configured and applied outbound route with a handoff number. Asterisk waits up to 30 seconds for an answer. Busy, rejection, timeout and connection failures retain the agent conversation; failure to restore audio terminates the call instead of leaving it stranded. On answer, the AI channel is removed and the caller and human remain bridged by Asterisk. The AI session and its usage end at handoff; the human conversation is not recorded or transcribed by the agent. Either party hanging up releases both legs.

The PBX/trunk must authorize outbound calls from the gateway. Asterisk remains in the media path; losing the gateway or ARI control drops active calls. Test the actual PBX before enabling production transfers. Successful configuration loading does not certify outbound routing, caller-ID acceptance, or interoperability.

Delete a connection

curl --fail-with-body "https://api.orbitali.ai/public/v1/telephony/sip/connections/$SIP_CONNECTION_ID" \
  -X DELETE \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

This deletes the connection and its linked SIP numbers. Disable the connection instead if you want to retain its configuration.

Errors

StatusCodeMeaning
400—Invalid input, unknown fields, invalid UUID, or missing allowlist
400SIP_OUTBOUND_PASSWORD_REQUIREDOutbound authentication has a username but no saved or supplied password
400SIP_INVALID_ALLOWLISTUse valid IPv4 addresses or CIDR prefixes
401UNAUTHORIZEDMissing or invalid API key
404—SIP is disabled
404SIP_NOT_FOUNDConnection absent or outside the key's organization
409SIP_ALLOWLIST_OVERLAPSource range overlaps another connection
409SIP_NO_CREDENTIALSPassword rotation requested for an IP connection
409PHONE_NUMBER_EXISTSNumber already exists on this connection

Adding a number also checks the account's phone-number allowance. Reuse an existing number or adjust the plan if the allowance is exhausted.

On this page