Skip to content

(708) 273-3111

CloudX Bot Line

Connect your own AI bot to CloudX

Connect your own AI voice bot to a CloudX Bot Line so it can take and place calls on your number.

CloudX Bot Line is a CloudX extension made for a voice bot you run yourself. Calls to your number reach your bot, and your bot can place calls from it. It is sold on its own and does not need Agent Console. This guide is for the engineer connecting the bot.

How setup works

XCLUTEL sets up every Bot Line. You do not sign in anywhere to configure it. You send us your bot's details and the number each bot answers. We connect it and run a test call with you.

What to send XCLUTEL

  • The secure WebSocket address (wss://) of your bot.
  • The number each bot should answer. Each number is its own Bot Line.
  • The extension or queue calls should go to if the bot cannot be reached (the fallback).
  • A technical contact for the test call.

What XCLUTEL gives you

  • A signing key, sent to you by secure handoff and never by email. Keep it in your own secret store, never in the bot's code.
  • A test call to confirm the line works before it takes real calls.

Your bot connects by web address, so you do not run a SIP server or open firewall ports for audio.

Web address

XCLUTEL's servers connect to your bot's WebSocket for each call and stream the audio both ways. Your bot does not register to anything.

Your bot's address

  • It must be a secure WebSocket address that starts with wss://.
  • It must be public. Private, local and internal addresses are refused.
  • Use a host name or a public IP address, with the standard port or 8443. No user name or password in the address.
  • It must answer the WebSocket upgrade directly. Our servers do not follow redirects.

How a call works

For each call our servers open a new connection to your address. Each message is a JSON text frame with an event field. If your bot does not accept the connection within 3 seconds, the call goes to the line's fallback and the caller never hears a dead line.

Event from XCLUTELWhat it means
connectedThe connection is open.
startThe call begins. It carries the call id (callSid), from, to, direction (inbound or outbound), customParameters and the audio format.
mediaCaller audio: base64 mu-law, 8 kHz, one channel, in 20 ms frames.
markSent back to you when playout reaches a mark you sent.
dtmfThe caller pressed a key. The digit is in the message.
stopThe call ended.
Event from your botWhat it does
mediaAudio for the caller: base64 mu-law, 8 kHz. Send any length. We cut it into 20 ms frames and play it in order.
markAsks us to tell you when everything sent before it has played.
clearDrops all audio still waiting to play. Use it for barge in, when the caller talks over the bot.
hangupEnds the call. Send {"event":"hangup"}.
transferMoves the call to an extension or queue on your own CloudX domain. Send {"event":"transfer","target":"1002"}.

A transfer target is a digit string of 2 to 8 digits that is a user or call queue on your domain. It cannot be one of your own Bot Line extensions. If we refuse a transfer, we send {"event":"error","code":"transfer_refused"} and the call keeps going.

Check the signature

Every connection carries an X-XCLUTEL-Signature header and an X-XCLUTEL-Timestamp header. The signature is the HMAC SHA-256 of the text timestamp.callSid.line, written as lowercase hex, using your signing key. The timestamp is in unix seconds, callSid is the call id from the start message, and line is the extension of the Bot Line.

Your bot should compute the same value and refuse the connection if it does not match, or if the timestamp is more than 5 minutes old. If your framework cannot read upgrade headers, the same values arrive in the start message customParameters as xclutel_signature, xclutel_timestamp and xclutel_line.

Limits and numbers

The Bot Line counts like any other line on your account.

  • Bot calls share your domain's call limit with everyone else on CloudX. If the bot takes many calls at once, ask XCLUTEL to size the limit for it.
  • Each number the bot answers needs its own line. Tell XCLUTEL which numbers should reach the bot.
  • Each Bot Line includes 2,000 minutes a month, inbound and outbound together. Minutes over that are billed at $0.025 a minute.
  • A Bot Line cannot dial 911 or other emergency and service numbers, so a caller in an emergency must use a regular phone.

XCLUTEL support

Who looks after which part.

XCLUTEL supports the Bot Line itself: our servers connecting to your bot, and calls reaching your bot and leaving it on your number. Our engineering team and techs look after everything on our side, end to end.

You own the bot: its software, its prompts and speech models, its hosting and its network. We can tell you what our servers see on a call, which is usually enough to find the problem.

Contact the support desk at (708) 273-3111 or [email protected], 24x7 for anything service affecting. Have the Bot Line number and the time of a test call ready.

Before you go live

Run these tests before the bot takes real calls. If one fails, the troubleshooting boxes above cover the usual causes.

  1. Your bot accepts our connection and refuses one with a wrong signature.
  2. Call your number from an outside phone: the bot answers, and both sides hear each other.
  3. Have the bot call an outside phone: the call connects, the audio works both ways, and the right caller ID shows.
  4. Hang up from each side once, and confirm the bot ends the call cleanly.

The product overview and plans are on the CloudX page.