Skip to main content

How it works

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-11-13 Version: v1.0

Base URL: https://<ringmaster-host>/v1 (local: http://localhost:8085/v1)

Short Description: Ringmaster is an engine for intelligent call centres. Services build their calling features on it (they are its client apps): the engine does the telephony, the call logic, the AI and the agents; the service owns its users, its screens and its business rules. A business on such a service (an account) gets phone numbers; each number plays a call flow (a script of blocks: greet, menu, collect a number, voicemail, AI agent, connect to a person…). Ringmaster also calls people (reminders, campaigns, callbacks, OTP codes), rings the business's agents in their browser, records and transcribes calls, and tells the client app what happened through signed webhooks. This book is for developers of a client app: every endpoint, every event the engine sends, every value.

Hints:

  • Every /v1 request carries the client app's API key: Authorization: Bearer <key>. Keep it on your server; never ship it to a browser or phone.
  • Ringmaster knows nothing about the client app's users, contacts, money or messages. It stores what it needs to ring and play: account settings, numbers, call flows, agents (a ref and a name), calls and their reports.
  • Phone numbers are always E.164 (+255745051250). Times in responses are UTC ISO 8601 (2026-11-13T14:41:00Z); times inside an account (opening hours, quiet hours, "call me at 9") are in the account's time zone (default Africa/Dar_es_Salaam).
  • Refusals you should handle in code come with a stable code (SCRIPT_IN_USE, VERSION_NOT_RUNNABLE…); switch on the code, show the message. Full list in Part 4.
  • How a call flow is written (all blocks, their settings and exits) is in SCRIPTS.md. This book covers the API around it.
  • A working sample client to try everything by hand: the demo console (console/, python3 console/serve.py); its "API calls" bar shows the exact request for each click.

Contents

Page What's in it
Part 1 — How Ringmaster works Read first: the objects, a call step by step, call-outs, flows and versions, agents, webhooks, app actions, recordings, costs, formats
Part 2A — Setup: basics, accounts, numbers ping, script schema and check · accounts · numbers
Part 2B — Call flows, media, knowledge scripts and versions · audio files · knowledge base for the AI
Part 2C — Calls, call-outs, OTP, reports call history, timeline, recording, transcript · quick calls and call-outs · OTP · stats and exports
Part 2D — Agents and live calls departments, agents, the browser desk · accept, hold, transfer, hang up
Part 2E — App actions and opt-outs registering the client app's actions and answering them · the do-not-call list
Part 3 — What the engine sends you webhooks: envelope, signature, retries, every event · agent desk signals
Part 4 — Reference every status and value · every error code · limits and defaults · glossary
Appendix — Not for client apps engine-internal routes · what the Ringmaster owner sets up with ringmaster-admin

Standard Response Format

Every response uses the Globe envelope.

Success

{
  "success": true,
  "httpStatus": "OK",
  "message": "Script",
  "action": null,
  "action_time": "2026-11-13T17:44:40.645991261",
  "data": { }
}

Error

{
  "success": false,
  "httpStatus": "CONFLICT",
  "message": "The script is still in use: move these to another script first",
  "code": "SCRIPT_IN_USE",
  "action_time": "2026-11-13T18:09:38.582694597",
  "data": { "numbers": ["+255677000003"] }
}
Field Type Description
success boolean true for success, false for errors
httpStatus string HTTP status, e.g. "200 OK", "409 CONFLICT"
message string Human-readable result; safe to show
code string Errors only: stable machine code to switch on (NOT_FOUND, VALIDATION_FAILED, SCRIPT_IN_USE…)
action_time string Server time of the response (local, no zone)
data any The payload; on errors, details (field messages, what is in the way) or null
HTTP code When
400 BAD_REQUEST Body is not valid JSON, a query parameter is missing or not the right type, a value is not allowed
401 UNAUTHORIZED Missing or wrong API key
403 CLIENT_SUSPENDED, FEATURE_OFF, CAN_CALL_REFUSED The app is suspended, the feature is not enabled for it, or its can-call check said no
404 NOT_FOUND No such object, or it belongs to another client app
409 a specific code A rule says no (in use, wrong state, already answered); data says what is in the way
422 VALIDATION_FAILED Field errors in data ({"field": "message"}), or a script's error list
429 RATE_LIMITED More requests per second than the app's limit
500 INTERNAL_ERROR A bug on our side; the message is generic

HTTP Method Badge Standards

  • GET - GET - read only
  • POST - POST - create / act
  • PUT - PUT - create or replace
  • PATCH - PATCH - change some fields
  • DELETE - DELETE - remove

Every endpoint at a glance

Group Method Path Page
Basics GET /v1/ping 2A
GET /v1/scripts/schema 2A
POST /v1/scripts/validate 2A
Accounts POST · GET /v1/accounts 2A
GET · PATCH /v1/accounts/{accountId} 2A
Numbers GET · POST /v1/numbers 2A
DELETE /v1/numbers/{numberId} 2A
POST /v1/numbers/{numberId}/assign · /release · /transfer 2A
PUT /v1/numbers/{numberId}/script · /ring-mode 2A
Scripts GET /v1/accounts/{accountId}/scripts 2B
PUT · GET · DELETE /v1/accounts/{accountId}/scripts/{ref} 2B
POST /v1/accounts/{accountId}/scripts/{ref}/versions 2B
GET /v1/accounts/{accountId}/scripts/{ref}/versions/{version} 2B
POST …/versions/{version}/runnable · …/versions/{version}/revoke 2B
GET …/versions/{version}/stats 2B
Media POST · GET /v1/accounts/{accountId}/media 2B
GET · DELETE /v1/media/{mediaId} 2B
Knowledge POST · GET /v1/accounts/{accountId}/kb-docs 2B
DELETE /v1/accounts/{accountId}/kb-docs/{documentId} 2B
Calls GET /v1/calls · /v1/calls/{callId} · /timeline · /recording · /transcript 2C
GET /v1/calls/export.csv 2C
POST /v1/calls (quick call) · /v1/calls/agent 2C
Call-outs POST · GET /v1/callouts 2C
GET /v1/callouts/{id} · /recipients · /stats · /export.csv 2C
POST /v1/callouts/{id}/recipients · /v1/callouts/{id}/{action} 2C
OTP POST /v1/otp 2C
Stats GET /v1/accounts/{accountId}/stats 2C
Agents GET /v1/accounts/{accountId}/agents · /agents/stats 2D
PUT · DELETE /v1/accounts/{accountId}/agents/{ref} 2D
PUT · POST · POST …/agents/{ref}/status · /ready · /lobby-token 2D
Departments POST · GET /v1/accounts/{accountId}/departments 2D
PUT · DELETE …/departments/{departmentId} 2D
PUT · GET …/departments/{departmentId}/members · /queue 2D
Live calls POST /v1/calls/{callId}/accept · /decline · /hold · /unhold · /transfer · /hangup 2D
App actions PUT · GET /v1/actions 2E
POST /v1/calls/{callId}/action-result 2E
Opt-outs POST · GET /v1/accounts/{accountId}/opt-outs 2E
DELETE /v1/accounts/{accountId}/opt-outs/{e164} 2E
Back to top