Skip to main content

API Reference

The Movoice API lets your application place AI calls, manage agents and contacts, send SMS and WhatsApp messages, and read call history, transcripts and totals. The complete, always-current description is the OpenAPI document: https://app.movoice.ai/api/v1/openapi.json (public, no key needed). Load it into Postman, Insomnia or a code generator. This page is the short guide; where the two differ, the OpenAPI document is right.

Base URL

Authentication

Send a secret key in the Authorization header:
Create keys on the Developer page in the dashboard. Each key carries scopes (calls:read, calls:write, agents:read, agents:write, contacts:read, contacts:write, numbers:read, sms:send, whatsapp:send, analytics:read, bookings:read, bookings:write, orders:write); a request without the scope an endpoint needs gets 403. Publishable keys (mv_pk_) work only for the chat widget. Orders from a shop, Zapier or n8n go to POST /api/orders with a key that holds orders:write. The body takes phone (required), name, amount, currency, items, address, orderId and paymentMode (cod or prepaid). A test key (mv_test_) gets a sample order back (livemode: false) and nothing is saved. API access is included on Scale and Enterprise, and on Starter and Growth with the API add-on.
Never put a secret key in client-side code or a public repository. Revoke a leaked key on the Developer page at once.

Test keys

A test key (mv_test_) never changes anything and never shows real customers:
  • Writes (place a call, hang up, create or change an agent or contact, send a message, start a test run) answer exactly as a live key would, with livemode: false, and nothing happens.
  • Reads of customer data (calls, a call and its transcript, contacts, caller memory, analytics) return a small fixed set of examples marked livemode: false. Example calls have the ids test_call_sample_1 and test_call_sample_2.
  • Your own set-up (agents, numbers, account, agent test runs) reads for real, so you can use a real agent id when you place a test call.

Endpoints

Agent languages

language on POST /agents and PATCH /agents/{id} takes exactly the languages the app offers; any case is accepted and the agent stores the app’s own spelling (od-in becomes od-IN). Odia is od-IN. Anything else is a 400 VALIDATION_ERROR on language that lists the accepted codes.
  • Speaks and listens (39): en-US en-IN en-GB hi-IN es-ES fr-FR de-DE it-IT pt-BR pt-PT pl-PL ru-RU ja-JP ko-KR zh-CN ar-SA tr-TR nl-NL sv-SE id-ID vi-VN fil-PH uk-UA el-GR cs-CZ fi-FI ro-RO da-DK no-NO hu-HU od-IN bn-IN ta-IN te-IN kn-IN ml-IN mr-IN gu-IN pa-IN
  • Listens only (12): sat-IN as-IN ur-IN ne-IN mai-IN kok-IN doi-IN brx-IN mni-IN ks-IN sd-IN sa-IN
  • Older mixes, still accepted: multi-hi-en, multi-hi-en-od

Place a call

201 returns the call (id, movoiceWebSocketCallId, agentId, phoneNumber, status, startedAt). The call meets the same account checks as a call started in the dashboard (see the error codes below), plus the pre-dial destination checks described in the OpenAPI document.

Book, move and cancel

Bookings go on the calendar the agent books on during a call (Google, Outlook, Cal.com or Calendly), with the same rules: business hours, no double booking, the customer’s confirmation and reminders.
  • 201 returns { id, status, date, time, durationMinutes, calendarSynced, confirmationSent }.
  • A time that was just taken is 409 with a message starting SLOT_TAKEN that lists the other free times that day.
  • POST /appointments/{id}/reschedule claims the new time first, moves the calendar event, and moves the reminders. If the calendar refuses, nothing changes (422).
  • POST /appointments/{id}/cancel takes the event off the calendar and stops the reminders.
  • Both tell the customer unless you send "tellCustomer": false: WhatsApp when it can go, else a text, else an email.
  • A test key books, moves and cancels nothing, and lists two example bookings (test_appt_sample_1, test_appt_sample_2).

Errors

Every error has the same shape:

Webhooks

Call events are sent to the webhook address you set on the Developer page. See Webhooks.