---
title: "[BETA] start call"
method: POST
path: "/instances/{id}/client/action/start-call"
tags: ["call"]
---

# \[BETA\] start call

`POST /instances/{id}/client/action/start-call`

## Request

- Base URL: `https://waapi.app/api/v1`
- URL: `https://waapi.app/api/v1/instances/{id}/client/action/start-call`
- Auth: HTTP bearer

Places a voice or video call. Limited to 10 per minute and 100 per hour per instance; the slot is taken before the media URLs are fetched, so a bad audioUrl or videoUrl still spends one. With waitForAnswer (default true) the response tells whether the callee picked up within answerTimeout; on timeout the instance hangs up. Optional audioUrl/imageUrl/videoUrl play after the call was answered; hangupAfterSeconds ends the call and counts from the moment the call connects, not from this response, so a call can last up to the 10 second connection wait plus hangupAfterSeconds. Over the limit the answer is `data.status: error` with `message: too many calls`, an `explanation` and `retryAfter` in seconds. Note: This endpoint is currently in beta and may change without notice.

## Path parameters

- `id` integer, required

## Request body

- object
  - `chatId` string, required: The number to call, as `number@c.us` or `number@lid`
  - `video` boolean: Place a video call instead of a voice call
  - `waitForAnswer` boolean: Wait for the callee to pick up before answering the request
  - `answerTimeout` integer: How long to wait for the callee to pick up, in milliseconds (waitForAnswer only). Capped at 45000: the request blocks for that whole time, and a longer wait would outlive the HTTP connection.
  - `audioUrl` string, uri: wav, mp3 or ogg played once after the call was answered, max 25 MB
  - `imageUrl` string, uri: Still image shown as the outgoing camera once the call connects; jpeg or png, max 25 MB
  - `videoUrl` string, uri: mp4 (H.264) looped as the outgoing camera after the call was answered, max 25 MB
  - `hangupAfterSeconds` integer: Hang up this many seconds after the call connected

## Response `200`

Request reached the instance. `data.status` reports whether the action was carried out; on error `data` carries `message` and `explanation`. Payload: the call plus whether it was answered.

- object
  - `status` 'success' | 'error': Whether the request reached the instance. `success` here does **not** mean the action was carried out — that is reported by `data.status`, which is the authoritative one. A malformed input arrives as `status: success` with `data.status: error`.
  - `data` union: The action's outcome. `status: success` carries the payload; `status: error` is an `actionError`.
    - object
      - `status` 'success', required: Whether the instance carried the action out — the authoritative field. In this branch it is always `success`; when the instance refused the action the whole `data` object is an `actionError` with `status: error`, `message` and `explanation`.
      - `instanceId` union
        - integer
        - string
      - `data` object
        - `call` Call
          - `id` string
          - `from` string: The peer — the caller for an incoming call, the callee for an outgoing one
          - `timestamp` integer
          - `isVideo` boolean
          - `isGroup` boolean
          - `fromMe` boolean: true for calls placed by this instance
          - `state` integer: The call's state, as the platform's own CallState enum — all fifteen members: 0 None, 1 Calling, 2 PreacceptReceived, 3 ReceivedCall (an incoming call is ringing), 4 AcceptSent, 5 AcceptReceived, 6 CallActive (connected), 7 CallActiveElseWhere (answered on another linked device), 8 ReceivedCallWithoutOffer, 9 Rejoining, 10 Link, 11 ConnectedLonely, 12 PreCalling (an outgoing call that is not registered yet), 13 CallStateEnding, 14 CallBCallStarting. In practice you will see 3, 6, 12 and 13; start-call with waitForAnswer false can report 12, and 7 reaches the call webhook. Treat any other value as one of the states above rather than as an error.
          - `answered` boolean: start-call only
          - `timedOut` boolean: start-call only: answerTimeout elapsed and the call was hung up
        - `answered` boolean: The callee picked up (waitForAnswer only)
        - `timedOut` boolean: answerTimeout elapsed and the instance hung the call up
    - ActionError: Shape of `data` when the instance refused the action. HTTP status is still 200 and the outer `status` is still `success`.
      - `status` 'error', required
      - `message` string
      - `explanation` string
      - `instanceId` union
        - integer
        - string

## Other responses

- `401`: Unauthorized — invalid or missing bearer token
- `403`: Forbidden — insufficient permissions or account blocked
- `404`: Not found — instance does not exist or does not belong to you
- `409`: Conflict — instance is not ready
- `422`: Validation error — invalid or missing request parameters
- `429`: Too many requests — rate limit exceeded

---

[API](https://skmtc.dev/waapi/apis/waapi-api-2.md) · [All operations](https://skmtc.dev/waapi/apis/waapi-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/waapi/apis/waapi-api-2/revisions/490302f75576?raw)