---
title: "Start an outbound call"
method: POST
path: "/conversation/outbound"
tags: ["Calls"]
---

# Start an outbound call

`POST /conversation/outbound`

Initiates an outbound telephony call with a specified agent and phone number.

**400 is returned for:**
- Invalid `agentId` format (`"Invalid agent id"`)
- Invalid `phoneNumber` format (`"Invalid phone number"`)
- Invalid `fromProductId` format (`"Invalid product id"`)
- Agent not found or not in the caller's org (`"Agent not found"`)
- Agent is archived (`"Agent is archived and cannot initiate calls"`)
- `workflow_graph` agent has no workflow configured (`"Workflow not found"`)
- Workflow has validation errors (`"Invalid workflow, please fix the errors..."`)

**403** is returned for `workflow_graph` agents when the org lacks conversational agents access.

**Test calls:** set the `x-test-call: true` header to mark the resulting call log as a test call
(`isTest: true`). Test calls are subject to concurrent slot limits.

## Headers

- `x-test-call` 'true'

## Request body

- object
  - `agentId` string, required — MongoDB ObjectId of the agent initiating the conversation
  - `phoneNumber` string, required — The E.164 phone number to call
  - `variables` object — Variables to inject into the agent's prompt at call time. Values must be string, number, or boolean — nested objects are not supported.
  - `fromProductId` string — ID of the telephony product (phone number) to call from. Get this from `GET /product/phone-numbers`.
  - `versionId` string — ID of a specific published agent version to use for this call. Useful for test calls — attributes the call log to that version so you can track which version was tested.
  - `operatorId` string — Integration operator identifier. Pass `"webengage"` to trigger the WebEngage integration flow.
  - `operatorData` object — Arbitrary data passed to the operator (e.g. `userId`, `journeyId` for WebEngage).

## Response `200`

Successfully started the outbound conversation

- object
  - `status` boolean
  - `data` object
    - `conversationId` string — The callId of the initiated call (format `CALL-{13-digit-timestamp}-{6-char-hex}`). Use this value as the `id` path parameter in `GET /conversation/{id}` and as an entry in `POST /conversation/search`.

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `500` — Internal server error

## Changes

- **2026-05-26** `7131fe74f3cb` — 5 info
  - added the new optional `header` request parameter `x-test-call`
  - added the new optional request property `operatorData`
  - added the new optional request property `operatorId`
  - added the new optional request property `versionId`
  - …1 more

[Change history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/conversation/outbound/post.md)

---

[API](https://skmtc.dev/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.dev/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/2bfbd089ccb3/schema)