Enable a Virtual Agent Experience

A Virtual Agent Experience receives inbound SIP INVITEs from Alianza for calls to assigned phone numbers. Typical use cases are AI receptionist, voicebot, IVR, and transfer-to-business workflows. By the end of this page, your SIP endpoint receives an inbound INVITE for every call dialled to a number you've been assigned.

For a comparison of Virtual Agent vs. Post-Call, see Post-Call vs. Virtual Agent. For a compressed sandbox run-through of these same steps, see the Virtual Agent quickstart.

The Virtual Agent integration pattern assumes you build on Twilio. See step 5 for what that means concretely. Support for alternative SIP infrastructure may be added in a future release.

Steps 1–4 are sequential API calls. Step 5 is what happens at your SIP endpoint once the connection is active.

Before you start

You can authenticate

You should already have:

• client_id and client_secret from Alianza onboarding.
• A way to obtain user-context tokens via the Authorization Code + PKCE flow.

The eligibility check in step 1 uses the Client Credentials grant (no user context). Steps 2–4 require a user-context token.

Alianza has what they need from you

Provide these to your Alianza onboarding contact before going live:

What Alianza will give you

Step 1 — Validate eligibility

Before prompting a user to connect your Experience, collect the phone number they want to use and verify that it is supported on the Alianza platform for your Experience type. For Virtual Agent, this is the number your agent will answer. This call uses the Client Credentials grant — no user context required.

The endpoint accepts PHONE_NUMBER, USER, and ACCOUNT target types — see the TargetType reference for per-type format rules. For Virtual Agent, use PHONE_NUMBER.

Request

GET {baseUrl}/experiences/{experienceId}/assignability
    ?targetType=PHONE_NUMBER
    &targetValue=+14155551234
Authorization: Bearer <access_token>

The full parameter table is on the reference page.

Response

{
  "experienceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "targetType": "PHONE_NUMBER",
  "targetValue": "+14155551234",
  "assignable": true
}

A response of assignable: false means the target cannot currently be used with this Experience — surface this to your user before proceeding. Note that a single telephone number may have at most one Virtual Agent Experience assigned to it.

Step 2 — Create the connection

An Experience Connection is the link between your Experience and a single Alianza account. It tracks configuration state and controls whether media flows.

This call requires a user-context token obtained via the Authorization Code + PKCE flow with scope experience-connections:manage.

A new connection starts in one of two states:

• INACTIVE — link exists but media is not flowing. Use this when your onboarding flow has a confirmation step before activation.
• ACTIVE — link exists and media will flow once an assignment is in place (step 3).

state is required.

Recommended: create as INACTIVE, then activate in step 4. This gives your UX a "confirm activation" moment after the assignment is in place.

Spec gap. A connection can be created directly in ACTIVE, but this guide treats activation as a separate step. The spec does not say whether create-as-ACTIVE and create-then-PUT-to-ACTIVE have identical side effects. Use the two-step flow until Alianza confirms equivalence.

Gap ID db519f112389

The tn query parameter is required. Alianza uses this phone number (E.164) to resolve the correct account when the authenticated user belongs to more than one. Use the same number you validated in step 1.

Spec gap. The spec does not document what happens when tn resolves to no account, or to multiple accounts the client can see. Confirm the failure modes with Alianza for multi-tenant integrations; assume 404 / 409 respectively until documented.

Gap ID 0020e2b9b0ca

If a connection already exists

A 409 Conflict means this account is already connected to your Experience. Do not surface that as an error to the user — discover the existing connection and reuse it, so a returning user flows straight through:

GET {baseUrl}/experience-connections?tn=+14155551234&experienceId=<your-experience-id>
Authorization: Bearer <user_access_token>

Take the id from the returned connection and continue from step 3 with it. This also makes your signup flow safe to replay: if a network error leaves you unsure whether the POST succeeded, the GET tells you.

Spec gap. The spec does not document Idempotency-Key support on POST /experience-connections, so a retry after a 5xx may or may not create a second connection. The 409 plus the lookup above is the documented recovery, but it is a read-after-write check rather than a true idempotency guarantee — treat the create as non-idempotent and always resolve through the GET before proceeding.

Gap ID 15659347b1ca

Request

POST {baseUrl}/experience-connections
    ?tn=+14155551234
Authorization: Bearer <user_access_token>
Content-Type: application/json

{
  "experienceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "INACTIVE"
}

Full body schema: ExperienceConnection.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountName": "Acme Communications",
  "experienceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "state": "INACTIVE"
}

Save these values. You will need both id (the Experience Connection ID) and accountId in the next steps.

Step 3 — Assign the Experience to a phone number

For Virtual Agent Experiences, an Experience Assignment binds your Experience to a single phone number — not to an account. Once an assignment exists and the connection is active (step 4), Alianza routes inbound calls dialled to that number to your SIP endpoint.

Use the accountId you saved from step 2 and the phone number you validated in step 1. This call requires the user-context token with scope experience-assignments:manage.

Request

POST {baseUrl}/experience-assignments
Authorization: Bearer <user_access_token>
Content-Type: application/json

{
  "experienceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountId":   "d4e5f6a7-b8c9-0123-def0-234567890123",
  "targetType":  "PHONE_NUMBER",
  "targetValue": "+14155551234"
}

Full body schema: ExperienceAssignment.

Response

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "experienceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountId": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "targetType": "PHONE_NUMBER",
  "targetValue": "+14155551234",
  "updatedAt": "2026-05-01T12:00:00Z"
}

Step 4 — Activate the connection

If the connection was created in INACTIVE state in step 2, activate it now. Activation signals Alianza to begin routing inbound SIP INVITEs for calls to the assigned phone number.

Send the complete Experience Connection resource (the response body from step 2) with the state field updated to ACTIVE. The same approach is used to deactivate later — set state back to INACTIVE.

This call requires the user-context token with scope experience-connections:manage.

Request

PUT {baseUrl}/experience-connections/{experienceConnectionId}
Authorization: Bearer <user_access_token>
Content-Type: application/json

{
  "id":           "550e8400-e29b-41d4-a716-446655440000",
  "accountId":    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "experienceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "state":        "ACTIVE"
}

Full body schema: ExperienceConnection.

Response

State transitions are unrestricted: a 409 Conflict means only that the connection is already in the requested state, so retrying after a 409 is harmless.

Step 5 — Receive SIP

Once the connection is ACTIVE and the assignment is in place, Alianza routes inbound calls dialled to the assigned phone number to your SIP endpoint via a Twilio SIP trunk, conforming to RFC 3261. Signalling is TLS (default port 5061), media is SRTP, and Alianza presents digest credentials negotiated during onboarding.

If your endpoint is unreachable, the call fails — there is no retry or fallback. See known issues 2–4 for the current Virtual Agent limitations.

The full SIP interface contract — network and transport requirements, authentication, caller-ID behaviour — is on the SIP interface page. Two deep-dives cover the call flows:

• Inbound call flow — the INVITE sequence from caller through Alianza and Twilio to your agent.
• Transfer to business — handing the call back to a human.

What's next

• Subscribe to webhook events to keep your system in sync when users change connections or assignments from an Alianza portal.
• Review the known issues before going to production.
• Building Post-Call as well? See Enable a Post-Call Experience.