WhatsApp Calling API
Manage incoming and outgoing voice calls using Meta Graph API v26.0, with agent ownership, current permission checks and reliable call history.
Requires the updated backend deployment and calling migration. Calling MCP tools require the updated package checkout and are pending npm publication.
Calling API reference for developers and AI
LLM ReadyFeed WACM API specs directly to Cursor, Claude, ChatGPT, Antigravity, or custom AI agents.
Authentication and requests
Base: https://app.wacm.in/api/v1/whatsappcall. Use a Sanctum bearer token and JSON. Company-scoped owner/staff access; 120 requests per minute. Generate a random session_id per browser media session and send it on call actions and polling reads.
/callsPaginated history: page, limit 1–100, contact_id, direction UIC/BIC, status, outcome, recipient search.
/calls/{id}Call detail; SDP is restricted to the owning agent and matching session_id.
/calls/{id}/notesSave notes (string, maximum 10000 characters).
/settingsLocal readiness, API version, business hours, visibility and last synchronization result.
/permissionRequired contact_id; refresh permission and allowed actions from Meta.
/permissioncontact_id and optional message; request free-form permission within Meta limits and messaging window.
/activeRecent incoming calls and this session’s current call (session_id).
/callscontact_id, SDP offer and session_id; connect an outbound call after checking current Meta permission.
/claimcall_id and session_id; atomically claim the call.
/pre-acceptcall_id, session_id and SDP answer; prepare incoming media.
/acceptcall_id, session_id and the identical SDP answer; accept incoming call.
/rejectcall_id and session_id; decline an incoming call.
/terminatecall_id and session_id; end or cancel an owned call.
/reports/statisticsperiod 1–90 calendar days (default 7); counts, answer rates and duration in minutes.
/reports/performanceSame period; daily chart, wait times in seconds and recent calls.
Media and lifecycle
Incoming: claim → capture microphone → create answer → pre-accept → wait for media connection → accept with the identical answer → enable microphone after acceptance. Meta can expire incoming calls after approximately 30–60 seconds. Outgoing: retain the peer connection after sending the offer and apply the answer from the connect event or call-detail polling. An HTTP success alone does not prove audible media.
The panel supports minimize, mute, devices, microphone check, elapsed time, sound activation, notes and call controls. Minimize preserves the call; navigation/reload does not transfer media. Private realtime events and four-second polling update the panel. Configure shared cache, timely workers, HTTPS and short-lived TURN credentials as needed.
Permissions and failure handling
Temporary and permanent permissions are supported. Always check Meta’s current allowed actions; cached permission can expire without a webhook. Responses use ok for actions, 422 for validation and 409 for competing ownership or invalid state. Preserve Meta error details and reconcile before retrying ambiguous connect timeouts. Permission requests outside the messaging window require an approved template flow, which this release does not implement.
MCP and scope
Six inspection tools: list_whatsapp_calls, get_whatsapp_call, get_whatsapp_calling_status, get_whatsapp_call_permission, get_whatsapp_call_statistics and get_whatsapp_call_performance. They provide no call mutations or media access. Recording/transcription events are retained as metadata; opt-in/download interfaces, voicemail, transfers and a DTMF keypad remain future work. Automated tests use mocked Meta and media; verify two-way audio with real devices before rollout.
Official Meta Calling documentation