SIP Integration

Overview

Aquant exposes each agent as a SIP endpoint. Your system places a normal SIP call (an INVITE) to the agent's SIP address; Aquant authenticates the call, answers it, and the AI agent converses with the caller in real time. There is no phone number involved on your side — routing is by an opaque SIP identity, which keeps the agent's underlying number private.

What you need before you start

SIP address & modes

Every SIP-enabled agent has a unique address. The user part is an unguessable, server-generated identifier — not the agent's phone number — so you can share it without exposing PSTN details.

Anatomy

Two modes, two domains

An address is issued for exactly one mode. The mode determines how Aquant answers the call and, crucially, what handover is possible. You cannot switch modes by changing the domain you dial — an address only resolves on its own domain.

Authentication

Inbound SIP calls are authenticated with digest (challenge/response) using your SIP credentials. Aquant challenges the first INVITE with 407 Proxy Authentication Required; your endpoint answers the challenge and re-sends the INVITE with a Proxy-Authorization header. Most SIP clients and PBXs do this automatically once you configure the username and password.

1. Send the initial INVITE

   Your endpoint sends an INVITE to the agent's SIP address. Aquant responds 100 Trying then 407 with a challenge (realm, nonce, qop=auth).

   # Aquant → you
   SIP/2.0 407 Proxy Authentication Required
   Proxy-Authenticate: Digest realm="sip.twilio.com",
     qop="auth", nonce="pYzyfw...ractXN", opaque="7e3552..."

2. Re-send with credentials

   ACK the 407, then send a second INVITE with a computed Proxy-Authorization digest response built from your SIP username and password.

   # you → Aquant
   Proxy-Authorization: Digest username="your-sip-user",
     realm="sip.twilio.com", qop=auth, nc=00000001,
     cnonce="634cbdc2", nonce="pYzyfw...ractXN",
     uri="sip:<sip_username>@aquant-call.sip.twilio.com",
     response="f69eb77f...1eed34", algorithm=MD5, opaque="7e3552..."

   On success Aquant answers 200 OK and the call is connected.

Placing a call

A complete, successful inbound call follows the standard SIP dialog, with one digest round-trip.

# Signaling sequence (you ↔ Aquant)
you    → INVITE                 # no credentials
Aquant → 100 Trying
Aquant → 407 Proxy Auth Required
you    → ACK
you    → INVITE                 # with Proxy-Authorization
Aquant → 100 Trying
Aquant → 180 Ringing
Aquant → 200 OK                 # call answered
you    → ACK
       ⇄ RTP media (PCMU)       # AI conversation
you    → BYE                    # hang up
Aquant → 200 OK

Caller identity

Every inbound call must carry the caller's identity in an X-Identity header on the INVITE. The value must be a valid phone number including the country and area code (E.164). Aquant records it against the call and makes it available in the call history.

Field

# INVITE header set by your endpoint — required, must be a phone number
X-Identity: +14155550123

What Aquant does with it

Media & codecs

Handover (Aquant → your SIP endpoint)

If your agent is configured for handover, the AI can transfer a live call to a destination you host — a human agent, or a downstream system such as a contact-center platform, IVR, or queue. Aquant places an outbound call to your endpoint and connects it with the caller. How it behaves depends on the agent's mode, and the two paths are not equivalent.

Cold transfer (Call mode)

Aquant re-points the live call at your SIP destination. The AI leaves the call at that moment — there is no announcement to the receiving party and no three-way period.

Warm transfer (Conference mode)

The caller is already in a conference. Aquant dials your destination into that same conference, so the AI, the caller and your agent are briefly on the call together.

Call reference (UUI)

Every SIP handover — cold or warm — carries the Aquant call id in a standard User-to-User header, so you can stitch the leg you just received to the call as Aquant recorded it. The value is a small JSON object, hex-encoded because braces and quotes are not safe in a SIP URI, with the encoding declared inline:

# On the outbound INVITE
User-to-User: 7b22757269223a2237383334373935362d...227d;encoding=hex

# hex-decoded
{"uri": "78347956-f990-449c-9566-ac66e7cd9fd4"}

Decode the hex to UTF-8 and parse the JSON; uri is the call record id. That is the same id accepted by the post-call summary endpoint, so a transferred call can be reconciled with its transcript and summary later — see After the call.

Behavior & rules

SIP responses

Standard SIP status codes you should handle. A 407 on the first INVITE is expected, not an error.

Full example

Snippets for the most common ways to originate the call. Replace the placeholders with your SIP address, credentials, and identity value.

SIPp (test scenario — the auth round-trip + identity)

<!-- INVITE with X-Identity; SIPp fills [authentication] from -au/-ap -->
<send retrans="500"><![CDATA[
INVITE sip:<sip_username>@aquant-call.sip.twilio.com SIP/2.0
Via: SIP/2.0/[transport] [local_ip]:[local_port];rport;branch=[branch]
From: "caller" <sip:caller@your-sbc>;tag=[call_number]
To: <sip:<sip_username>@aquant-call.sip.twilio.com>
Call-ID: [call_id]
CSeq: 1 INVITE
Contact: <sip:caller@[local_ip]:[local_port]>
X-Identity: +14155550123
Content-Type: application/sdp
Content-Length: [len]

v=0
o=caller 1 1 IN IP[local_ip_type] [local_ip]
s=-
c=IN IP[media_ip_type] [media_ip]
t=0 0
m=audio [media_port] RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
]]></send>
# run:
sipp aquant-call.sip.twilio.com:5060 -sf scenario.xml -m 1 \
  -au "your-sip-user" -ap "your-sip-password"

Asterisk (PJSIP dialplan — set identity, dial the trunk)

; register a trunk to the Aquant SIP domain with your SIP credentials,
; then add the identity header and dial the agent's sip_username.
exten => _X.,1,Set(PJSIP_HEADER(add,X-Identity,+14155550123)=)
 same => n,Dial(PJSIP/<sip_username>@aquant-trunk)

FreeSWITCH (dialplan — sip_h_ injects a custom header)

<action application="set" data="sip_h_X-Identity=+14155550123"/>
<action application="bridge" data="sofia/gateway/aquant/<sip_username>"/>

After the call

When the agent has recording and analysis enabled, Aquant transcribes the call and generates a summary once it ends. The summary is available over the ACAI REST API, so a SIP integration can pull conversation outcomes back into your CRM or ticketing system without screen-scraping the console.

Authenticate first

Exchange your ACAI API credentials for a short-lived bearer token (valid one hour, refreshed on use), then call the summary endpoint with it. The token is bound to one agent, and the endpoint only returns calls handled by that agent.

# 1 — get a session token
POST https://acai-api.aquant.ai/acai/auth
{ "api_key": "...", "api_secret": "...",
  "agent_id": "...", "sender_id": "your-system" }

# 2 — read the summary
GET https://acai-api.aquant.ai/acai/call/{call_record_id}/summary
Authorization: Bearer <token>

Response

{
  "call_record_id": "6cbd7ac0-33ab-4790-9c3c-bdfc64a4e079",
  "status": "Ready",
  "summary": "The caller reached out for assistance regarding..."
}

Changelog

What changed in this revision of the reference. Behaviour that was already live but undocumented is marked clarified.