---
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.

## Caller-ID resolution

When `fromProductId` is omitted **and** the agent has no telephony
product attached, the call dispatches from a Smallest-managed Plivo
trunk using a default caller-ID number (chosen by destination
country). The call still places and the response is still
`200 + conversationId`, but the recipient sees the default Smallest
number rather than your own. For production traffic, either:

- pass `fromProductId` explicitly (look up your owned numbers via
  `GET /product/phone-numbers`), or
- attach a phone-number product to the agent.

## Resolved-config check

The call uses the agent's currently-active version. If your most
recent prompt change went through `PATCH /workflow/{workflowId}` and
the agent has versioning enabled, that change may not have
propagated to the active version — and the call will play the
platform-default greeting instead of your prompt. Before placing a
production call, fetch `GET /agent/{agentId}` and confirm
`_resolvedConfig.firstMessage` (and related fields) match what you
intended. The
[Versioning Lifecycle](/atoms/developer-guide/build/agents/versioning-lifecycle)
guide covers the correct edit flow.

**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

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/versions/6d1036a76fbc/schema)