Appearance
Integrating with Calloop
A step-by-step guide for a developer connecting their product to Calloop: what Calloop does for you, the choices you make up front and which one fits your project, then each integration step in order. This guide links to the contract documents for the full detail; it doesn't repeat every field.
Working with an AI assistant? Connect it to Calloop's MCP server and it can read these docs and set up your account while it writes your integration: Build with an AI assistant.
1. What Calloop does, and what you build
Calloop is a standalone call engine. Your customers call over WhatsApp or a phone number; your users (agents) answer in a browser or a mobile app; Calloop does everything in between.
| Calloop does | You build |
|---|---|
| Receives calls from WhatsApp and SIP carriers, and places outbound calls | Your product's backend: who your users are, which numbers they have, what to show |
| Routes calls: queues, IVR menus, personal lines, transfers, timeouts, overflow | A small token endpoint that proves to Calloop who a user is |
| Carries the audio (WebRTC to your app; Calloop's media servers) | Your app's screens: ringing, in-call, history. The SDK does the calling |
| Keeps the call record, recordings, reports and supervisor monitoring | A webhook receiver, if you want call events in your own database |
| Sends push notifications to wake your app for a call | Your push credentials (Firebase, Apple, OneSignal), stored in Calloop. Optional where the Calloop deployment provides shared ones |
Calloop has its own database and knows nothing about your product. It stores your own ids (*_ref fields, external_ref) and data (consumer_metadata) and hands them back, but never interprets them. You never read Calloop's database and Calloop never reads yours.
Words used below
| Term | Meaning |
|---|---|
| Consumer | Your product, as Calloop knows it. It holds your API keys, signing keys, webhook and push credentials. |
| Tenant | A workspace inside your product: one business you serve, or your whole product. |
| Agent | Anyone who answers calls: a support employee, or an end user of your app. SUPERVISOR agents can also watch the board and listen in. |
| Channel (line) | A number calls arrive on: a WhatsApp number, or a phone number (DID) on a SIP trunk. |
| Queue | Where calls to a shared line wait for an available agent. |
| Ref | Your own id for a tenant, agent, queue or line. You address everything by your refs; you never need Calloop's ids. |
2. How your system talks to Calloop
Your backend ──① REST API (API key)──────────────►┐
Your backend ◄──② events + lookup (signed)────────┤
Your app ◄─③ socket + WebRTC (JWT) ──────────►│ CALLOOP ◄──⑤── WhatsApp / SIP carriers ◄── customers
User's phone ◄──④ push (your FCM / APNs) ─────────┘| # | Interface | Direction | Used for | Contract |
|---|---|---|---|---|
| ① | Management API (/v1, REST) | your backend → Calloop | Set up tenants, agents, lines and queues; start outbound calls; read calls, reports and recordings; delete data | management-api.md |
| ② | Events (webhook) and the lookup hook | Calloop → your backend | Learn what happened (call created, answered, ended…); name or reject a caller before it rings | events.md |
| ③ | Agent socket + WebRTC, through the SDK | your app ↔ Calloop | Ring, answer, hang up, transfer, availability, supervisor board and monitoring, the audio itself | agent-protocol.md, SDK READMEs |
| ④ | Push | Calloop → your users' devices | Wake the app for an incoming call (Android data message, iOS CallKit, web push) | agent-protocol.md → Push |
| ⑤ | Channels | carriers / Meta → Calloop | Where customer calls come from | management-api.md → Channels |
Security model in one line: your backend is trusted with an API key; your app never is. The app only ever holds a short-lived token your backend signed for one user.