CRM integration guide

How the pieces fit

1. Connect. The customer's administrator creates an API token in the Ringura console with the scopes below and gives it to the CRM. A token belongs to one Ringura account and sees only that account's data.
2. Map users. The CRM matches its users to Ringura agents with GET /api/v1/agents and keeps each agent's id.
3. Subscribe. The CRM registers its webhook endpoint with POST /api/v1/webhook-endpoints and stores the signing secret.
4. Click-to-call. A click on a number in the CRM sends POST /api/v1/calls with the agent's id.
5. Screen-pop. When an agent takes a call or a chat, the routing.assigned event names the agent and the conversation; the CRM reads the contact and opens the matching record.
6. Log back. Events and the interaction records give the CRM what to write on its activity: channel, direction, times, the agent's disposition and the outcome.
7. Outcomes. Deposits and conversions the CRM knows about go back with POST /api/v1/outcomes or POST /api/v1/deposits, and Ringura attributes them to the agent, campaign and channel that last touched the contact.

Base URL: https://api.ringura.com/api/v1/. Accounts on a reseller's own console domain use that domain instead. Times are ISO 8601 in UTC and phone numbers E.164. The API overview covers pagination, idempotency and the conventions every operation shares.

API tokens and scopes

An administrator whose console session has passed MFA creates tokens in the console's Developer page, choosing the scopes and the limit of requests a minute. Send the token as Authorization: Bearer cck_... on every request; a token in a URL is never accepted. The account's API allow-list of IP addresses applies, so tell your customers which addresses your CRM calls from.

Ask for the scopes your integration uses and no more. A token without the scope an operation needs is answered 403 insufficient_scope, with the scope it needs in required.

Building one integration for many Ringura accounts? Talk to sales before you start.

Click-to-call

POST /api/v1/calls rings the agent's phone first and then the number, presented from one of the account's verified numbers. Name the agent with agentId, or a queue with queueId to give the call to the queue's first free voice agent; one of the two is required. A call for a queue with no free agent waits up to 15 minutes for one.

number is E.164, or a national number with defaultCountry (two capital letters, such as GB). contactId ties the call to a Ringura contact, callerId chooses one of the account's verified numbers, and purpose is service (the default) or marketing, which needs the contact's recorded consent. Send an Idempotency-Key made from the CRM's own id for the click, so a retry after a timeout never places a second call.

curl -X POST 'https://api.ringura.com/api/v1/calls' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: crm-call-7f3c9a21-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "+441632960000",
  "agentId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e",
  "contactId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8f",
  "purpose": "service"
}'

Every request passes the checks any outbound call passes: calling hours where the callee is, the do-not-call list and suppressions, consent for marketing, and one call to the same number in 10 minutes. A call that goes ahead is answered 201 with the request. status is dialling (the agent's phone is ringing) or waiting_agent (no free agent in the queue yet). Keep id and callId on the CRM activity.

{
  "request": {
    "id": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d90",
    "source": "api",
    "e164": "+441632960000",
    "purpose": "service",
    "status": "dialling",
    "refusal": null,
    "agentId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e",
    "queueId": null,
    "contactId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8f",
    "callId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d91",
    "createdAt": "2027-01-04T09:00:00.000Z",
    "dialledAt": "2027-01-04T09:00:00.000Z"
  }
}

Refusals

A call the checks refuse is answered 409. error holds the reason, message says it in words, and request is the refused request as recorded:

{
  "error": "after_hours",
  "message": "the call was refused: after_hours",
  "request": {
    "id": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d92",
    "source": "api",
    "e164": "+441632960000",
    "purpose": "service",
    "status": "refused",
    "refusal": "after_hours",
    "agentId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e",
    "queueId": null,
    "contactId": null,
    "callId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d93",
    "createdAt": "2027-01-04T21:30:00.000Z",
    "dialledAt": null
  }
}

Treat any other error on a 409 the same way: show message to the user and do not retry by yourself. A 400 is a mistake in the request: bad_number (not a phone number), unknown_agent, unknown_queue, unknown_caller_id (the account has no verified number to call from) or bad_request (neither an agent nor a queue named).

Screen-pop and contact lookup

To open the CRM record when an agent takes a call or a chat, subscribe to routing.assigned. Its data names the agentId and the conversationId. Read the conversation for its contactId, then the contact for its phone numbers and e-mail addresses (identifiers), and open the matching record for the CRM user mapped to that agent.

To go the other way, from a CRM record to Ringura, look the contact up by phone or e-mail: GET /api/v1/contacts?phone=%2B441632960000. The phone number is E.164, and its + is written %2B in a query string; a bare + reads as a space and the request is answered 400.

Contacts carry no field for the CRM's own id, so keep the Ringura contact id on the CRM record. A CRM record with no Ringura contact yet can be created with POST /api/v1/contacts and at least one e164 or email identifier. Subscribe to contact.merged to update the id you keep when two contacts become one.

Logging calls and outcomes back

Register the CRM's endpoint with POST /api/v1/webhook-endpoints: its url (https, on a public address), the eventTypes it wants, and an optional description. The answer carries the signing secret once; store it encrypted. GET /api/v1/event-types lists every type you can subscribe to.

Each delivery is a JSON POST with the headers CC-Event-Id, CC-Event-Type, CC-Delivery-Id and CC-Signature, and this body:

{
  "id": "evt_...",
  "type": "dialler.disposition",
  "tenantId": "...",
  "createdAt": "2027-01-04T09:04:12.000Z",
  "data": {
    "campaignId": "...",
    "attemptId": "...",
    "leadId": "...",
    "agentId": "...",
    "code": "sale"
  }
}

The events a CRM usually logs:

For the call itself, list the conversation's interactions with GET /api/v1/interactions?conversationId=...: each one has its channel, direction, status, startedAt, endedAt and the remote and local addresses. When the agent finishes the work in the CRM rather than in Ringura, update the conversation with status resolved and a disposition.

Outcomes the CRM records, such as a sale or a deposit, go back with POST /api/v1/outcomes (up to 500 at a time; externalRef makes each one count once) or POST /api/v1/deposits for a back office's deposits. A follow-up an agent must do is a task: POST /api/v1/tasks routes it to a queue like a conversation.

Verifying webhook signatures

CC-Signature is t=<unix seconds>,v1=<hex>, with a second v1 while a secret rotates. The v1 value is the HMAC-SHA-256, under the endpoint's secret, of the timestamp, a full stop and the raw request body. Check it against the raw bytes before parsing the JSON, reject timestamps more than 5 minutes away, and remember each delivery you accepted by its timestamp and body until its timestamp is too old, so a replayed request is refused.

Node.js

// Verify a webhook delivery (Node.js 18 or later, no dependencies).
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;
// Deliveries already accepted (a digest of the timestamp and the body), each kept until its
// timestamp is too old to be accepted anyway. With several processes, keep them in your database.
const seen = new Map();

/**
 * header:  the CC-Signature request header
 * rawBody: the request body exactly as received (a Buffer or a string)
 * secrets: your endpoint secret, or [new, old] while a rotation is under way
 * Returns true only for a genuine delivery that has not been seen before.
 */
export function verifyWebhook(header, rawBody, secrets, nowMs = Date.now()) {
  let t = null;
  const v1 = [];
  for (const part of String(header ?? '').split(',')) {
    const [k, v = ''] = part.split('=').map((s) => s.trim());
    if (k === 't' && /^[0-9]{1,12}$/.test(v)) t = Number(v);
    else if (k === 'v1' && /^[0-9a-f]{64}$/.test(v)) v1.push(v);
  }
  if (t === null || v1.length === 0) return false;
  const now = Math.floor(nowMs / 1000);
  if (Math.abs(now - t) > TOLERANCE_SECONDS) return false;
  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
  const genuine = [secrets].flat().some((secret) => {
    const want = createHmac('sha256', secret).update(`${t}.`).update(body).digest();
    return v1.some((got) => timingSafeEqual(want, Buffer.from(got, 'hex')));
  });
  if (!genuine) return false;
  // A replay is the same timestamp and body, whichever of its signatures it still carries:
  // during a rotation a delivery has two, and resending it with only one is still a replay.
  const key = createHash('sha256').update(`${t}.`).update(body).digest('hex');
  for (const [k, until] of seen) if (until < now) seen.delete(k);
  if (seen.has(key)) return false;
  seen.set(key, t + TOLERANCE_SECONDS);
  return true;
}

// With node:http:
//   const chunks = [];
//   req.on('data', (c) => chunks.push(c)).on('end', () => {
//     const raw = Buffer.concat(chunks);
//     if (!verifyWebhook(req.headers['cc-signature'], raw, process.env.CC_WEBHOOK_SECRET)) return res.writeHead(401).end();
//     res.writeHead(204).end();
//     handle(JSON.parse(raw)); // a retry is a new delivery: use the CC-Event-Id header to ignore an event you already handled
//   });

Python

# Verify a webhook delivery (Python 3.8 or later, standard library only).
import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300
# Deliveries already accepted (a digest of the timestamp and the body), each kept until its
# timestamp is too old to be accepted anyway. With several processes, keep them in your database.
_seen = {}


def verify_webhook(header, raw_body, secrets, now=None):
    """header:   the CC-Signature request header
    raw_body: the request body exactly as received (bytes)
    secrets:  your endpoint secret, or [new, old] while a rotation is under way
    Returns True only for a genuine delivery that has not been seen before."""
    t = None
    v1 = []
    for part in str(header or "").split(","):
        key, _, value = part.partition("=")
        key, value = key.strip(), value.strip()
        if key == "t" and re.fullmatch(r"[0-9]{1,12}", value):
            t = int(value)
        elif key == "v1" and re.fullmatch(r"[0-9a-f]{64}", value):
            v1.append(value)
    if t is None or not v1:
        return False
    now = int(time.time() if now is None else now)
    if abs(now - t) > TOLERANCE_SECONDS:
        return False
    body = raw_body if isinstance(raw_body, bytes) else str(raw_body).encode("utf-8")
    signed = str(t).encode("ascii") + b"." + body
    genuine = False
    for secret in [secrets] if isinstance(secrets, str) else secrets:
        want = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(want, got) for got in v1):
            genuine = True
    if not genuine:
        return False
    # A replay is the same timestamp and body, whichever of its signatures it still carries:
    # during a rotation a delivery has two, and resending it with only one is still a replay.
    key = hashlib.sha256(signed).hexdigest()
    for k, until in list(_seen.items()):
        if until < now:
            del _seen[k]
    if key in _seen:
        return False
    _seen[key] = t + TOLERANCE_SECONDS
    return True

# In a web framework, pass the raw body bytes, never the parsed JSON (Flask: request.get_data()).
# Answer 401 when verify_webhook() is False, else 2xx, and use the CC-Event-Id header to ignore
# an event you already handled: a retry or a replay is the same event again.

Retries, duplicates and idempotency

• Answer with a 2xx status once the event is safely stored. Anything else is retried: 8 attempts in all, the wait doubling from 30 seconds (at most 6 hours, plus up to 20% jitter). After the last attempt the delivery is dead.
• Ignore an event you have already handled by its event id (CC-Event-Id, the body's id), not by CC-Delivery-Id: a replay is a new delivery of the same event.
• A delivery that is retried can arrive after a later event. Compare createdAt before overwriting a newer state in the CRM.
• List the dead letter with GET /api/v1/webhook-deliveries?status=dead and replay a delivery once your endpoint is fixed.
• Rotating the secret signs with both the new and the old secret for 24 hours, so the CRM can switch without missing a delivery.
• Every write you send can carry an Idempotency-Key (8 to 100 letters, digits or _ . : -). A retry with the same key and body gets the first answer with Idempotent-Replayed: true; the same key with another body is answered 422. Keys are kept for 24 hours.

Recordings and transcripts

API v1 has no operation for call recordings or transcripts, and an interaction carries no link to either. If your integration needs them, tell us.

What the API does give for history: the messages of a conversation on text channels, and bulk exports of the conversations, work_items, dial_attempts, outcomes and insights datasets as CSV, JSON lines or Parquet. An export is built in the background; the export.ready event, or reading the export, says when to download it.

Rate limits

Each token has its own limit of requests a minute, set when it is created. Every answer carries RateLimit-Limit and RateLimit-Remaining; over the limit, the answer is 429 rate_limited with Retry-After in seconds. Wait that long before the next request.

A CRM with many users shares one token per Ringura account, so send its requests through one queue that respects these headers rather than from each user's session. Lists return at most 200 rows a page (limit) and continue with cursor; for a large backfill, use an export instead of paging.

Error codes

Errors are JSON: { "error": "code", "message": "..." }, with problems listing each field that did not fit on a 400. The codes a CRM meets:

Testing your integration

• API v1 has no sandbox mode: every call placed with POST /api/v1/calls is a real call. Test with a Ringura account kept for testing, agents whose phones you hold and destination numbers you own.
• In unit tests and mocks, use numbers from the range set aside for drama, such as +441632960000, and the example ids from the API reference.
• Webhook endpoints must use https and resolve to public addresses, and redirects are not followed, so expose a local receiver through an https tunnel while you develop.
• Exercise your receiver without placing calls: replay a delivered delivery with the replay operation, and check that the second copy is ignored.
• Test a refusal: a second click-to-call to the same number within 10 minutes is refused with too_soon.
• Rotate the secret while your receiver runs and check that deliveries signed with both secrets are accepted once.

Downloads

• Postman collection (format v2.1): a CRM integration folder with the calls of this guide in order, then every API v1 operation by group. Set the collection variable token, and agentId, queueId, conversationId and webhookUrl for the CRM folder; baseUrl is https://api.ringura.com. Writes send a new Idempotency-Key each time.
• Node.js example (Node.js 18 or later, no dependencies): agent list, contact lookup, click-to-call with refusals, webhook subscription, and a receiver that verifies signatures and ignores duplicates. Run node crm-example.mjs for its commands.
• Python signature check: the code above, as a file.
• OpenAPI document (OpenAPI 3.1): generate a client in your own language.