Virtual Agent quickstart

In about 10 minutes you'll go from client_id and client_secret to an inbound SIP INVITE landing on your endpoint when someone dials your assigned test number.

Prerequisites

  • client_id, client_secret, experienceId from Alianza onboarding.
  • A test phone number eligible for your Experience and provisioned for inbound routing.
  • A SIP endpoint reachable from Alianza's sandbox IPs (TLS, port 5061).
  • A Virtual Agent built on Twilio — the integration path described and tested in these docs. Other SIP infrastructure may work, but has not yet been thoroughly tested.

Use sandbox: https://api.b2.alianza.com.

1. Get a token (Client Credentials)

curl -X POST https://auth.beta.alianza.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=experience-assignability:check"

Export the resulting access_token as $TOKEN.

2. Check eligibility

curl -G "https://api.b2.alianza.com/experience/experiences/$EXPERIENCE_ID/assignability" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "targetType=PHONE_NUMBER" \
  --data-urlencode "targetValue=+14155551234"

Expect {"assignable": true, ...}.

3. Get a user-context token

Run the Authorization Code + PKCE flow end-to-end and export the access token as $USER_TOKEN. Required scopes: experience-connections:manage experience-assignments:manage.

4. Create an Experience Connection

curl -X POST "https://api.b2.alianza.com/experience/connections?telephoneNumber=+14155551234" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"experienceId":"'"$EXPERIENCE_ID"'","state": "INACTIVE"}'

Expect 201. Save the response id as $CONNECTION_ID and accountId as $ACCOUNT_ID.

5. Assign to the phone number

For Virtual Agent, target the phone number (not the account):

curl -X POST https://api.b2.alianza.com/experience/assignments \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"experienceId":"'"$EXPERIENCE_ID"'","accountId":"'"$ACCOUNT_ID"'","targetType":"PHONE_NUMBER","targetValue":"+14155551234"}'

Expect 201.

6. Activate the connection

curl -X PUT "https://api.b2.alianza.com/experience/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"'"$CONNECTION_ID"'","accountId":"'"$ACCOUNT_ID"'","experienceId":"'"$EXPERIENCE_ID"'","state":"ACTIVE"}'

Expect 200 with state: ACTIVE.

7. Receive a test call

Dial the test phone number from any phone. Note that +14155551234 is only an example, and real test phone numbers for you to use will be provided by Alianza. Alianza routes the inbound INVITE to your SIP endpoint via the Twilio trunk. See Inbound call flow for the full sequence.

What's next

  • Read the full Virtual Agent journey — call-flow details, transfer-to-business, failure modes.
  • Building Post-Call instead? See the Post-Call quickstart. The differences from above: target the account in step 5 (not a phone number) and your SRS receives SIPREC instead of SIP.