Skip to main content
These APIs let an application place outbound voice calls to customers and track them until they end. The API supports a proactive customer-engagement requirement:
  • An external event or an app triggers a call.
  • The voice agent conducts the conversation for answered calls.
  • The calling app can monitor and act on the call.
A few specific use cases are:
  • Remind user for an upcoming appointment.
  • Verify user-placed orders.
  • Send delivery notification or seek confirmation.
  • Call as a follow-up of a user’s contact request.
Pre-configured channels manage the telephony operations, infrastructure, and provider details. It makes the API simple to use by focusing on outcomes such as answered, busy, not answered, or failed calls. After a call is answered, it’s handed over to an Artemis agent as a normal agent conversation. It uses idempotency to prevent unnecessary repeat calls.

Prerequisites

  • An outbound-capable KoreVG voice channel.
  • A project-bound Platform API key (abl_…). Send it in the x-api-key header.
  • The outbound_calls.initiate scope on the key to place and terminate calls. The outbound_calls.read scope to look up, list, summarize, search, and stream calls.

Call lifecycle

A call moves through these phases in order: accepted, dialing, ringing, in_progress, and terminal. A call that connects creates a session. When a call is terminal, its outcome shows how it ended: completed, busy, rejected, no_answer, machine, failed, canceled, or expired. Placing a call returns at once with the phase accepted. Track the call by looking it up, by listing or searching the call log, or by subscribing to its event stream.

List of endpoints

All paths start with /api/v1/project/{projectSlug}/{env}/outbound-calls.

Behavior to know

  • Each request to place a call needs an idempotencyKey. Repeating the same request returns the original call. Reusing the key with a different body returns 409. Use one key per business event, such as one per booking, so a retry doesn’t ring twice.
  • Pass the values the agent’s ON_START reads in sessionMetadata.
  • Responses always mask the destination number. To find a call by number, use the search endpoint.
  • A call that belongs to a different project returns 404, not 403.