Hosted Service

This chapter is for customers on the Vexyl-hosted service. Vexyl runs the gateway for you, so you never see a server or a configuration file. You connect your PBX, your web page and your webhook receiver to endpoints we give you.

What you receive

Item	What it is	What you do with it
SIP trunk target	A Vexyl address that accepts calls from your PBX	Point a trunk at it (next section)
WebSocket endpoint and API key	A `wss://` address and a key for browser voice sessions	Put both in your web page
Webhook secret	The key we sign lifecycle events with	Use it to verify each event you receive
DID to bot mapping	Done by Vexyl on our side	Tell us what you want per DID

Connect your PBX to the trunk

There is no SIP registration. Your PBX carries a pjsip trunk to the Vexyl address we give you, and we recognise it by your PBX's public IP address. Follow the PBX steps in the customer PBX side of the SIP trunk chapter.

Send us:

Your public static IP address, or the block your ISP gives you.
The DIDs (phone numbers) that should reach the bot.
For each DID, the bot, language and voice you want.
Your codec preference.

We allow your egress IP or block on our side. We hand out one of two trunk types:

Trunk type	Codecs	`qualify_frequency`
Vexyl Asterisk front	Opus with FEC, mu-law, A-law	`15`
Gateway SIP bridge, direct	G.711 only	not set (leave it off)

On the Asterisk front, qualify keeps the NAT pinhole open. Without it, the bot's hang-up can fail to reach your PBX on longer calls.

; Vexyl Asterisk front. No registration section: hosted trunks do not register.
[vexyl-gw]
type=endpoint
context=from-vexyl
transport=<your-udp-transport>
aors=vexyl-gw
disallow=all
allow=opus,ulaw,alaw
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes

[vexyl-gw]
type=aor
contact=sip:<vexyl-gw-address>
qualify_frequency=15

[vexyl-gw]
type=identify
endpoint=vexyl-gw
match=<vexyl-gw-address>

You choose the inbound context name to suit your dialplan. The SIP trunk chapter has the full walkthrough and the FreePBX GUI equivalents.

For the direct-bridge flavour, omit qualify_frequency entirely (the default is off) and use allow=ulaw,alaw.

A changing public IP is the one recurring cause of outages on this service. Ask your ISP for a static IP, and tell us before your address changes.

You set two things in the page: the wss://<endpoint-we-give-you> address and the API key. We allow the web origins you list, so send us every domain that will embed the widget. The key goes in the page as a ?apiKey= query value or an x-api-key header. A wrong key closes the session with code 4001; reaching your call limit closes it with 4003. See the browser widget chapter for the page code.

Webhooks

Give us a URL. We send it call.started and call.ended events as JSON, with the header X-Webhook-Type: lifecycle. See the webhooks chapter for the payload.

To verify an event:

Take the raw request body exactly as received, before any JSON parsing.
Compute an HMAC-SHA256 of that body, keyed with the secret we gave you.
Write the result as lowercase hexadecimal.
Read the X-Webhook-Signature header.
Compare the two values; compare them with your language's constant-time comparison function.
Reject the request if they differ.

Outbound calls and per-call settings

The HTTP API is not exposed to hosted customers. Outbound calls and per-call settings (for example a different bot or voice for one call) are requested through Vexyl. The HTTP API chapter describes what exists, so you know what to ask for.

Changing bots, languages, voices

Send us a request. Per DID we can set the bot, the language, the speech provider and the voice to use. There is no routing API for you to call. For a custom voice, we design or replicate it and give you its id.

Getting help