Xura Global AI Voice Agents

Overview

Xura Global AI Voice Agents make and answer phone calls for your organization in natural spoken Sinhala. Each agent knows who it is talking to from your CRM, follows the call profile agreed with your team, answers questions from your own documents, and sends the result of every call back to your systems.

Every organization connects in the same way: three integration points link your systems with the agents, and calls travel over your own phone line.

What organizations use it for

The integration is the same for all of them. Only the call profile is specific to your organization: what the agent says, what it needs to know and what it records. Each organization also gets its own dedicated system and pays AI and phone usage directly to Google and its telecom operator (see your system and costs).

Integration process

Every project follows the same five phases. Steps marked Mandatory are needed before go-live; the others depend on how you use the agents.

1. 1

   Plan

   Agree the call profilesBoth teamsMandatory

   Decide what each kind of call should achieve, what the agent may say, which contact fields it needs and which outcomes you want back. Call profiles

   Order the phone lineYour teamYour operatorMandatory

   Order a SIP trunk and phone numbers from a licensed telecom operator and choose how it connects (option A, B or C). Start early: operator provisioning is often the longest step. Phone line

   Set up your accountsYour teamMandatory

   Create a Google Cloud project with billing (for Gemini and Speech-to-Text) and decide where your system runs: on a server in your name or hosted by Xura Global. Your system and costs

   Exchange addresses and keysBoth teamsMandatory

   Base URLs, API keys, the webhook signing secret and firewall addresses, for testing and for production. Onboarding checklist

2. 2

   Build

   Build the Contact API ①Your teamMandatory

   Two read-only endpoints that return a contact and the facts for the call. Needed for inbound calls and campaigns. Contact API

   Build the webhook receiver ②Your teamMandatory

   One HTTPS endpoint that verifies and stores the result of every call. Webhook receiver

   Connect your systems to the Voice API ③Your teamFor outbound calls

   Start calls and campaigns from your systems and show results in your own front end. Not needed if the agents only answer calls. Voice API

   Prepare knowledge documentsYour teamRecommended

   Products, services, procedures, fees, policies and frequent questions the agents may answer from. Knowledge base

   Install and configure your systemXura GlobalMandatory

   Xura Global installs your dedicated system, connects it to your Google Cloud project, sets up your call profiles, voice and calling hours, and loads your knowledge documents.

3. 3

   Connect

   Connect the phone line ④Your teamYour operatorXura GlobalMandatory

   Connect the SIP trunk to the Xura Global gateway and make test calls in both directions. Phone line

   Connect WhatsApp callingYour teamXura GlobalOptional

   Let customers call you on WhatsApp, and call them there once they allow it. WhatsApp calling

4. 4

   Test

   Run the acceptance testsBoth teamsMandatory

   Tests of data, results, calls, knowledge and campaigns, run together in the testing environment. Testing and go-live

5. 5

   Go live

   PilotBoth teamsMandatory

   Start with a small group of contacts. Review transcripts and outcomes together and adjust the profiles.

   Roll out and monitorBoth teamsMandatory

   Switch to production keys and numbers. Failed webhooks, Contact API errors and phone line faults alert both teams.

Who does what

Your system and running costs

Every organization gets its own dedicated system: its own server (or its own isolated Docker installation), database, telephony gateway and API keys. Nothing is shared with other organizations, and usage is billed directly to your own accounts.

• Maintenance plan (optional). Software updates, security patches, monitoring, backups and support. Without a plan, Xura Global helps on request.
• Budget alert. Set a monthly budget alert in your Google Cloud project so AI costs never surprise you.
• Keep billing enabled. Under Google's terms for paid use, the Gemini API does not use your call data to improve Google's products, and Speech-to-Text does so only if you opt in to data logging.

Call profiles

A call profile describes one kind of call: its purpose, what the agent says and checks, the contact data it needs and the outcomes it records. Your team and Xura Global agree each profile at the start of the project; Xura Global configures it and you approve it with test calls. An organization can have several profiles, for example a payment reminder for outbound calls and a customer service line for inbound calls.

What a profile defines

1. PurposeThe goal of the call, in one sentence.
2. DirectionOutbound, inbound or both, and on which numbers.
3. GreetingHow the agent introduces itself and your organization.
4. Identity checkWhat the agent confirms before it discusses any detail.
5. Context fieldsThe facts the agent needs from your Contact API.
6. Outcomes and captured dataThe result codes and values you want back.
7. Rules and limitsWhat the agent may agree to, and what it must never say.
8. HandoverWhen the agent promises a call back from your staff.
9. Calling hours and retriesHours, days, holidays, attempts and the gap between attempts.
10. Voice and knowledgeThe agent's voice and the documents it may answer from.

Example profiles

Starting points that are adapted to each organization. The meaning of every code is in Reference codes.

Every profile also uses the standard outcome codes, such as CALLBACK_REQUESTED, OPT_OUT and NO_ANSWER.

How the agents behave on every call

These rules are built into every agent and apply to all profiles. Your profile can add to them but not remove them.

• The agent introduces itself with your organization's name, and says it is an automated assistant when asked.
• It confirms it is speaking to the right person before discussing any personal detail, and never discusses a contact's details with anyone else.
• It answers only from your contact data and your knowledge base, and never invents figures, dates or policies. What it cannot answer becomes a call-back request.
• It stays polite and never threatens, pressures or argues.
• It reads important details (dates, times, amounts) back and waits for the contact to confirm them.
• When a contact asks not to be called again, it ends the call politely and reports OPT_OUT.
• It never calls contacts marked doNotCall, and campaigns call only within your calling hours. A call ends after 10 minutes at most.

Changing a profile. Tell Xura Global what should change. Wording and rules change after a test call; new context fields or outcome codes are agreed with your team first because they change the data you send or receive.

How a call flows

Outbound call

Your system asks the agents to call one contact. The agent fetches fresh data from your Contact API before it dials, so it never uses old figures.

sequenceDiagram
    autonumber
    participant Y as Your system
    participant X as Xura Voice API
    participant C as ① Contact API
    participant P as Contact's phone
    participant W as ② Webhook
    Y->>X: POST /v1/calls
    X->>C: GET /contacts/{id}
    C-->>X: 200 contact
    X-->>Y: 202 queued
    X->>P: Rings the phone (④)
    P-->>X: Answers
    X->>W: call.started
    Note over X,P: Conversation in Sinhala
    X->>W: call.completed
    W-->>X: 200 OK
          

Inbound call

A contact calls one of your numbers. The agent looks the caller up by phone number while it greets them.

sequenceDiagram
    autonumber
    participant P as Contact's phone
    participant X as Xura AI Voice Agent
    participant C as ① Contact API
    participant W as ② Webhook
    P->>X: Calls your number (④ or WhatsApp)
    X->>C: GET /contacts/lookup?phone=…
    C-->>X: 200 contact, or 404 unknown
    X->>W: call.started
    Note over P,X: Agent confirms the name, then helps
    X->>W: call.completed
          

Campaign

A campaign calls a list of contacts automatically, one after another, only within the calling hours you set. Unanswered calls are retried.

sequenceDiagram
    participant Y as Your system
    participant X as Xura Voice API
    participant W as ② Webhook
    Y->>X: POST /v1/campaigns
    X-->>Y: 201 running
    loop Each contact, within calling hours
        X->>X: Fetch contact (①) and dial
        X->>W: call.completed or call.not_connected
    end
    Note over X: No answer or busy:<br/>retried after retryMinutes,<br/>up to maxAttempts
    X->>W: campaign.completed
          

Conventions

These rules apply to ①, ② and ③.

Built by your team1Contact API

A small read-only API in front of your CRM. The agents call it to find out who they are talking to and what the call is about. It has two endpoints and returns one object, the contact.

GET /xura/v1/contacts/lookup?phone=%2B94771234567 HTTP/1.1
Host: api.your-company.com
Authorization: Bearer ck_live_4f7c9b1e…
Accept: application/json

{ "error": { "code": "not_found", "message": "No contact uses this phone number." } }

{
  "contactId": "C-10042",
  "name": "Nimal Perera",
  "spokenName": "නිමල්",
  "salutation": "මහත්තයා",
  "phone": "+94771234567",
  "language": "si",
  "doNotCall": false,
  "context": {
    "amountDue": 5000,
    "currency": "LKR",
    "dueDate": "2026-08-10"
  }
}

Contact object

Send only these fields. The agents do not need, and should not receive, national ID numbers, addresses or full account histories.

Context examples

{ "amountDue": 5000, "currency": "LKR", "dueDate": "2026-08-10" }

{ "appointmentAt": "2026-10-02T09:30:00+05:30", "withWhom": "Dr. Perera", "location": "Kandy branch" }

{ "orderNo": "ORD-55812", "deliveryDate": "2026-09-27", "codAmount": 12500, "currency": "LKR" }

• Use the formats in Conventions: numbers for amounts, YYYY-MM-DD for dates, ISO 8601 for times.
• Include only what the agent needs to say or check. It uses context only after the identity check.
• Never include passwords, PINs, full card or account numbers, national ID numbers or detailed medical information.

Errors and time limits

Built by your team2Webhook receiver

One HTTPS endpoint on your side. We send it an event every time something happens to a call or a campaign. Your endpoint must:

• Accept POST requests with a JSON body at a public HTTPS URL, for example https://api.your-company.com/webhooks/xura.
• Check the signature on every request and reject requests that fail it.
• Answer with a 2xx status within 10 seconds. Save the event first and do the slow work (CRM updates, SMS) afterwards.
• Process each event once. The same event can arrive more than once, so skip any id you have already stored.
• Not rely on arrival order. Use occurredAt to order events for the same call.

Event types

Envelope

Every event has the same outer shape:

Headers we send

Verifying signatures

We sign every request with a secret that only you and Xura Global know (the webhook signing secret, starting with whsec_, shared at onboarding). Checking it proves that the request came from Xura Global and was not changed on the way.

1. Read t (Unix time in seconds) and v1 (the signature) from the X-Xura-Signature header.
2. Compute HMAC-SHA256 of t + "." + raw request body with the secret, as lowercase hex. Use the raw bytes exactly as received, before any JSON parsing.
3. Compare it with v1 using a constant-time comparison.
4. Reject the request with 401 if the signatures differ or if t is more than 5 minutes away from your clock.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.XURA_WEBHOOK_SECRET; // whsec_…

app.post('/webhooks/xura', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries(
    (req.get('X-Xura-Signature') ?? '').split(',').map((p) => p.split('=')),
  );
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${parts.t}.`)
    .update(req.body) // raw bytes
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const valid =
    parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!fresh || !valid) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  saveEvent(event); // store it, then process asynchronously (skip if event.id is already stored)
  res.sendStatus(200);
});

import hashlib, hmac, json, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["XURA_WEBHOOK_SECRET"].encode()  # whsec_…

@app.post("/webhooks/xura")
def xura_webhook():
    header = request.headers.get("X-Xura-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")
    body = request.get_data()  # raw bytes
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
        abort(401)

    event = json.loads(body)
    save_event(event)  # store it, then process asynchronously (skip duplicate event ids)
    return "", 200

@PostMapping("/webhooks/xura")
public ResponseEntity<Void> xuraWebhook(
        @RequestHeader("X-Xura-Signature") String signature,
        @RequestBody byte[] body) throws Exception {

    Map<String, String> parts = Arrays.stream(signature.split(","))
        .map(p -> p.split("=", 2)).filter(p -> p.length == 2)
        .collect(Collectors.toMap(p -> p[0], p -> p[1]));
    long t = Long.parseLong(parts.getOrDefault("t", "0"));

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
    String expected = HexFormat.of().formatHex(mac.doFinal(body)); // raw bytes

    boolean fresh = Math.abs(Instant.now().getEpochSecond() - t) <= 300;
    boolean valid = MessageDigest.isEqual(
        expected.getBytes(StandardCharsets.UTF_8),
        parts.getOrDefault("v1", "").getBytes(StandardCharsets.UTF_8));
    if (!fresh || !valid) return ResponseEntity.status(401).build();

    events.save(body); // store it, then process asynchronously (skip duplicate event ids)
    return ResponseEntity.ok().build();
}

$secret = getenv('XURA_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input'); // raw bytes
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_XURA_SIGNATURE'] ?? ''), $sig);

$expected = hash_hmac('sha256', ($sig['t'] ?? '0') . '.' . $body, $secret);
$fresh = abs(time() - (int) ($sig['t'] ?? 0)) <= 300;
if (!$fresh || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
save_event($event); // store it, then process asynchronously (skip duplicate event ids)
http_response_code(200);

Retries

If your endpoint does not answer with a 2xx within 10 seconds, we send the same event again (same id):

After the sixth attempt the event is marked as failed and both teams are alerted. The result is not lost: you can always read it with GET /v1/calls/{callId}, and we can send failed events again once your endpoint is back.

Payload examples

call.completed

The outcome.data values depend on the call profile. Two examples:

{
  "id": "evt_5f0c2b7e9d8a4c21",
  "type": "call.completed",
  "occurredAt": "2026-09-25T04:45:41Z",
  "apiVersion": "v1",
  "data": {
    "call": {
      "id": "3ec2bcda-8289-4a84-90bc-46fc2f80f77a",
      "direction": "outbound",
      "channel": "phone",
      "profile": "payment-reminder",
      "status": "completed",
      "contactId": "C-10042",
      "phone": "+94771234567",
      "externalRef": "INV-2026-08-00123",
      "metadata": { "branch": "Kandy" },
      "campaign": null,
      "startedAt": "2026-09-25T04:44:50Z",
      "endedAt": "2026-09-25T04:45:38Z",
      "durationSec": 48,
      "endReason": "agent_completed"
    },
    "outcome": {
      "code": "PROMISE_TO_PAY",
      "summary": "Nimal promised to pay the overdue LKR 5,000 on 2 October 2026. The agent read the date back and he confirmed it.",
      "sentiment": "POSITIVE",
      "data": { "promisedDate": "2026-10-02", "promisedAmount": 5000, "currency": "LKR" },
      "followUp": null
    },
    "transcript": [
      { "role": "agent", "text": "ආයුබෝවන්! මම ඒබීසී සමාගමෙන් කතා කරන්නේ. මට නිමල් මහත්තයා එක්ක කතා කරන්න පුළුවන්ද?", "at": "2026-09-25T04:44:51Z" },
      { "role": "contact", "text": "ඔව්, නිමල් කතා කරන්නේ.", "at": "2026-09-25T04:44:58Z" },
      { "role": "agent", "text": "නිමල් මහත්තයා, අගෝස්තු දහවෙනිදා ගෙවන්න තිබුණ රුපියල් පන්දාහක මුදලක් තවම ගෙවලා නැහැ. ඒක කවදා ගෙවන්න පුළුවන්ද?", "at": "2026-09-25T04:45:00Z" },
      { "role": "contact", "text": "මම ලබන සිකුරාදා ගෙවන්නම්.", "at": "2026-09-25T04:45:21Z" },
      { "role": "agent", "text": "එතකොට ඔක්තෝබර් දෙවෙනිදා රුපියල් පන්දාහ, හරිද?", "at": "2026-09-25T04:45:23Z" },
      { "role": "contact", "text": "ඔව්, හරි.", "at": "2026-09-25T04:45:31Z" },
      { "role": "agent", "text": "ස්තූතියි නිමල් මහත්තයා. සුභ දවසක්!", "at": "2026-09-25T04:45:33Z" }
    ]
  }
}

{
  "id": "evt_2b9e71c4d05a8f36",
  "type": "call.completed",
  "occurredAt": "2026-09-25T05:31:12Z",
  "apiVersion": "v1",
  "data": {
    "call": {
      "id": "8d4a0f6e-2c31-4b7a-9e15-6f0b3c8d2a91",
      "direction": "outbound",
      "channel": "phone",
      "profile": "appointment-reminder",
      "status": "completed",
      "contactId": "P-2291",
      "phone": "+94712345678",
      "externalRef": "APT-77120",
      "metadata": null,
      "campaign": { "id": "CAMP-6D2E91AF", "attempt": 1, "willRetry": false, "nextAttemptAt": null },
      "startedAt": "2026-09-25T05:30:14Z",
      "endedAt": "2026-09-25T05:31:09Z",
      "durationSec": 55,
      "endReason": "agent_completed"
    },
    "outcome": {
      "code": "RESCHEDULE_REQUESTED",
      "summary": "Sunitha cannot come on 2 October and asked to move the appointment to Monday 5 October. Staff should confirm a time.",
      "sentiment": "NEUTRAL",
      "data": { "requestedDate": "2026-10-05" },
      "followUp": { "reason": "Confirm a new appointment time on 5 October 2026.", "preferredTime": null }
    },
    "transcript": [
      { "role": "agent", "text": "ආයුබෝවන්! මම ඒබීසී මෙඩිකල් සෙන්ටර් එකෙන් කතා කරන්නේ. සුනීතා මහත්මිය එක්කද මම කතා කරන්නේ?", "at": "2026-09-25T05:30:15Z" },
      { "role": "contact", "text": "ඔව්.", "at": "2026-09-25T05:30:21Z" },
      { "role": "agent", "text": "සුනීතා මහත්මිය, ඔබට ඔක්තෝබර් දෙවෙනිදා උදේ නවයයි තිහට වෛද්‍ය පෙරේරා මහතා හමුවෙන්න වේලාවක් වෙන් කරලා තියෙනවා. ඔබට එදාට එන්න පුළුවන්ද?", "at": "2026-09-25T05:30:23Z" },
      { "role": "contact", "text": "එදාට බැහැ, ඊළඟ සඳුදා පුළුවන්.", "at": "2026-09-25T05:30:40Z" },
      { "role": "agent", "text": "හරි, එහෙනම් ඔක්තෝබර් පස්වෙනිදා සඳුදාට වෙනස් කරන්න ඉල්ලීමක් දාන්නම්. අලුත් වේලාව තහවුරු කරන්න අපේ කාර්ය මණ්ඩලය ඔබට කතා කරයි.", "at": "2026-09-25T05:30:43Z" },
      { "role": "contact", "text": "හරි, ස්තූතියි.", "at": "2026-09-25T05:30:58Z" }
    ]
  }
}

call.not_connected (a campaign attempt that will be retried)

{
  "id": "evt_8a41d3c09b7e2f65",
  "type": "call.not_connected",
  "occurredAt": "2026-09-25T05:02:41Z",
  "apiVersion": "v1",
  "data": {
    "call": {
      "id": "b7f9e2c1-4d3a-4c8e-9f61-2a5d7e0c9b13",
      "direction": "outbound",
      "channel": "phone",
      "profile": "appointment-reminder",
      "status": "not_connected",
      "contactId": "P-2307",
      "phone": "+94763456789",
      "externalRef": "APT-77134",
      "metadata": null,
      "campaign": { "id": "CAMP-6D2E91AF", "attempt": 1, "willRetry": true, "nextAttemptAt": "2026-09-25T06:32:41Z" },
      "startedAt": "2026-09-25T05:02:10Z",
      "endedAt": "2026-09-25T05:02:41Z",
      "durationSec": 0,
      "endReason": "no_answer"
    },
    "outcome": { "code": "NO_ANSWER", "summary": "The call was not answered.", "sentiment": null, "data": null, "followUp": null }
  }
}

call.started

{
  "id": "evt_1c7e4b92a0d35f8e",
  "type": "call.started",
  "occurredAt": "2026-09-25T05:20:03Z",
  "apiVersion": "v1",
  "data": {
    "call": {
      "id": "e41f7a2b-9c6d-4e1f-8b3a-5d2c9f0e7a64",
      "direction": "inbound",
      "channel": "phone",
      "profile": "customer-service",
      "status": "in_progress",
      "contactId": "C-10042",
      "phone": "+94771234567",
      "startedAt": "2026-09-25T05:20:03Z"
    }
  }
}

campaign.completed

{
  "id": "evt_d93b0e5f7c2a4186",
  "type": "campaign.completed",
  "occurredAt": "2026-09-25T11:30:05Z",
  "apiVersion": "v1",
  "data": {
    "campaign": {
      "id": "CAMP-6D2E91AF",
      "name": "October appointment reminders",
      "profile": "appointment-reminder",
      "channel": "phone",
      "status": "completed",
      "startedAt": "2026-09-25T03:30:00Z",
      "finishedAt": "2026-09-25T11:30:05Z",
      "totals": { "contacts": 120, "reached": 94, "notReached": 21, "skipped": 5 },
      "byOutcome": {
        "CONFIRMED": 68,
        "RESCHEDULE_REQUESTED": 13,
        "CANCELLED": 4,
        "CALLBACK_REQUESTED": 6,
        "WRONG_PERSON": 3,
        "NO_ANSWER": 17,
        "BUSY": 4
      }
    }
  }
}

Call and outcome fields

Call

Outcome

Transcript

A list of { role, text, at } entries in call order. role is agent, contact or kb (a knowledge-base lookup: text is the question looked up and sources lists the documents used). The contact's words are transcribed automatically and can contain recognition errors; the outcome fields are the reliable record of what was agreed.

Provided by Xura Global3Voice API

Your back end calls this API to start calls and campaigns, read results and manage the knowledge base. Call it from your servers only: the API key must never be placed in a web page or a mobile app.

Basics

Calls

curl https://voice-api.example.com/v1/calls \
  -H "Authorization: Bearer xv_test_9b2e…" \
  -H "Idempotency-Key: 6c1d2c1e-0f7a-4d52-9c1b-2f8e7a3d4b10" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "C-10042", "profile": "payment-reminder", "externalRef": "INV-2026-08-00123", "metadata": { "branch": "Kandy" } }'

{
  "id": "3ec2bcda-8289-4a84-90bc-46fc2f80f77a",
  "direction": "outbound",
  "channel": "phone",
  "profile": "payment-reminder",
  "status": "queued",
  "contactId": "C-10042",
  "phone": "+94771234567",
  "externalRef": "INV-2026-08-00123",
  "createdAt": "2026-09-25T04:44:21Z"
}

{
  "profile": "appointment-reminder",
  "contact": {
    "contactId": "P-2291",
    "name": "Sunitha Fernando",
    "spokenName": "සුනීතා",
    "salutation": "මහත්මිය",
    "phone": "+94712345678",
    "context": { "appointmentAt": "2026-10-02T09:30:00+05:30", "withWhom": "Dr. Perera", "location": "Kandy branch" }
  },
  "externalRef": "APT-77120"
}

Campaigns

{
  "name": "October appointment reminders",
  "profile": "appointment-reminder",
  "contactIds": ["P-2291", "P-2307", "P-2315"],
  "maxAttempts": 3,
  "retryMinutes": 90,
  "callingHours": {
    "start": "09:00",
    "end": "18:00",
    "days": ["MON", "TUE", "WED", "THU", "FRI", "SAT"],
    "skipDates": ["2026-10-20"]
  },
  "start": true
}

{
  "id": "CAMP-6D2E91AF",
  "name": "October appointment reminders",
  "profile": "appointment-reminder",
  "channel": "phone",
  "status": "running",
  "totals": { "contacts": 3, "done": 0, "pending": 3, "calling": 0, "skipped": 0 },
  "createdAt": "2026-09-25T03:29:47Z"
}

{
  "id": "CAMP-6D2E91AF",
  "status": "running",
  "totals": { "contacts": 3, "done": 1, "pending": 1, "calling": 1, "skipped": 0 },
  "byOutcome": { "RESCHEDULE_REQUESTED": 1 },
  "items": [
    { "contactId": "P-2291", "status": "done", "attempts": 1, "lastOutcome": "RESCHEDULE_REQUESTED", "lastCallId": "8d4a0f6e-…" },
    { "contactId": "P-2307", "status": "pending", "attempts": 1, "lastOutcome": "NO_ANSWER", "nextAttemptAt": "2026-09-25T06:32:41Z" },
    { "contactId": "P-2315", "status": "calling", "attempts": 1, "lastOutcome": null }
  ]
}

Profiles

{
  "data": [
    {
      "id": "payment-reminder",
      "name": "Payment reminder",
      "directions": ["outbound", "inbound"],
      "contextFields": [
        { "name": "amountDue", "type": "number", "required": true },
        { "name": "currency", "type": "string", "required": true },
        { "name": "dueDate", "type": "date", "required": true }
      ],
      "outcomes": ["PROMISE_TO_PAY", "ALREADY_PAID", "FINANCIAL_HARDSHIP", "REFUSED_TO_PAY", "DISPUTED"],
      "captures": [
        { "name": "promisedDate", "type": "date" },
        { "name": "promisedAmount", "type": "number" },
        { "name": "paidDate", "type": "date" }
      ]
    }
  ],
  "nextCursor": null
}

Knowledge base

The agents answer questions about your products, services and procedures from these documents. Instruction documents tell the agents how to work (tone, limits, when to hand over to your staff) and are always used. Knowledge documents hold the facts they answer from. Changes apply from the next call.

{
  "title": "ශාඛා සහ විවෘත වේලාවන් (Branches and opening hours)",
  "type": "knowledge",
  "language": "si",
  "content": "# සෙනසුරාදා\n- හැම ශාඛාවක්ම උදේ 9.00 සිට දවල් 1.00 දක්වා විවෘතයි…"
}

{
  "type": "knowledge",
  "fileName": "service-procedures.pdf",
  "fileBase64": "JVBERi0xLjQKJ…"
}

{
  "id": "DOC-4B7E19C2",
  "title": "ශාඛා සහ විවෘත වේලාවන් (Branches and opening hours)",
  "type": "knowledge",
  "language": "si",
  "enabled": true,
  "characters": 1320,
  "passages": 6,
  "updatedAt": "2026-09-25T04:10:12Z"
}

{ "question": "සෙනසුරාදා ශාඛා ඇරලා තියෙනවද?" }

{
  "answer": "ඔව්. හැම ශාඛාවක්ම සෙනසුරාදා උදේ නවයේ ඉඳන් දවල් එක වෙනකම් ඇරලා තියෙනවා.",
  "passages": [
    { "documentId": "DOC-4B7E19C2", "title": "ශාඛා සහ විවෘත වේලාවන්", "heading": "සෙනසුරාදා", "score": 0.84 }
  ]
}

Webhook and settings

{
  "url": "https://api.your-company.com/webhooks/xura",
  "events": ["call.completed", "call.not_connected", "campaign.completed"]
}

{
  "voice": "Kore",
  "defaultCallingHours": { "start": "08:00", "end": "19:00", "days": ["MON", "TUE", "WED", "THU", "FRI", "SAT"] }
}

event: call.transcript
data: {"callId":"3ec2bcda-…","entry":{"role":"contact","text":"ඔව්, නිමල් කතා කරන්නේ.","at":"2026-09-25T04:44:58Z"}}

Errors

Errors use standard HTTP status codes and this body:

{
  "error": {
    "code": "contact_not_found",
    "message": "Contact C-99999 was not found in your Contact API.",
    "requestId": "req_8f2c61d09a"
  }
}

Quote the requestId when you contact us about an error.

Your team, your telecom operator and Xura Global4Phone line (SIP trunk)

The agents make and receive ordinary phone calls over a SIP trunk: phone lines that a licensed telecom operator delivers over an IP network. Your organization orders the trunk and its numbers from the operator and keeps that contract and its call charges. Xura Global connects the trunk to the telephony gateway in your system.

Connection options

Requirements

What each side provides

Routing and handover

• Inbound. Every call to a number routed to the agents is answered by an agent, day and night. To send only some calls, route them in your PBX (option B).
• Outbound. Calls show your caller ID. Campaign calls are placed only within your calling hours; calls you start one by one through the Voice API are placed straight away.
• Handover to staff. In version 1 the agents do not transfer live calls. When a contact needs a person, the agent promises a call back and the result arrives as CALLBACK_REQUESTED with the reason.

OptionalWhatsApp calling

Customers can also call your organization on WhatsApp, and the agents can call customers on WhatsApp once they allow it. WhatsApp is an extra line, not a separate system: the calls reach the same agents, use the same Contact API and send the same webhook events, with channel: "whatsapp".

How it connects

Meta connects WhatsApp calls for your business number to the gateway in your system over SIP, using the WhatsApp Business Calling API. Meta requires encrypted signalling (SIP over TLS) and encrypted audio (SRTP); the gateway handles both.

What you need

• A WhatsApp Business Platform (Cloud API) account for your organization. Numbers used in the WhatsApp Business app cannot be used.
• The WhatsApp number your customers will call, enabled for calling. Meta requires the number to have a messaging limit of at least 2,000 unique recipients a day.
• Access for Xura Global to set up calling on that number in your Meta business account, or your WhatsApp provider points the number's SIP calling to the address we give you. A number has one SIP destination for calls; your WhatsApp messages are not affected.
• For outbound calls: an approved message template that asks customers for permission to call.

Meta's rules for WhatsApp calls

Meta changes these rules from time to time. The current rules are in Meta's WhatsApp Business Calling documentation.

In the API

• Inbound. We look up the caller's WhatsApp number with your Contact API as usual. If WhatsApp does not share the caller's number, the caller is treated as unknown.
• Outbound. POST /v1/calls or POST /v1/campaigns with channel: "whatsapp". A contact who has not given permission is reported as call.not_connected with FAILED and end reason no_whatsapp_permission, and is not retried.
• Permission requests are sent from your WhatsApp Business account with your approved template, by Xura Global on your behalf or by your own WhatsApp system.

Security and data protection

Onboarding checklist

Both teams exchange the following before testing starts. Send secrets through a password manager or an encrypted channel, never by plain email.

Testing and go-live

Acceptance tests

We run these together in the testing environment. Each must pass before go-live; test 15 applies only if you use WhatsApp.

Go-live checklist

• All acceptance tests passed and signed off by both teams
• Call profiles and knowledge documents approved by your business and compliance teams
• Production keys and the signing secret exchanged and stored in secrets stores
• Firewalls allow your system's address; production webhook URL set
• Google Cloud billing enabled and a monthly budget alert set
• Production trunk: numbers routed to the agents, caller ID and allowed destinations checked
• Calling hours, holidays and do-not-call flags checked; opt-outs update your CRM
• Pilot with a small group of contacts, reviewed before the full rollout
• Monitoring agreed: failed webhooks, Contact API errors and phone line faults alert both teams

Reference codes

Standard outcome codes

Used by every call profile.

Profile outcome codes (examples)

End reasons

Call status

queued → dialing → in_progress → completed. A call that is not answered goes from dialing to not_connected. Inbound calls start at in_progress.

Campaign status

draft → running ⇄ paused → completed or stopped. A campaign completes when every contact has a final result.

Each contact in a campaign is pending (waiting for its first call or a retry), calling, done (has a final result) or skipped (not called: do-not-call, not found in your Contact API, or no WhatsApp permission).

Document history