Goodbox

API Reference > Calling

Initiate Individual Call

Create an outbound voice call to a single number. Set the call window with `call_start_time` / `call_end_time`, identify the experience with `chatbot_id`, constrain daily dialing with `call_config`, and optionally enable callbacks.

POST/v1/api-routes/voice-calls/createTry it

Authentication headers

  • `x-api-key` (required): your API key.
  • `x-api-secret` (required): your API secret.

Phone number format

  • `from_number` and `mobile_number` must be valid strings in the format your workspace expects (typically E.164 with country code, e.g. `+911234567890` and `+919999999999`).
  • Invalid numbers can cause the call to fail.

Request body

  • `chatbot_id` (required): ID of the chatbot that handles the call.
  • `from_number` / `mobile_number` (required): caller ID and callee number.
  • `is_auto_from_number`: when `true`, the platform may pick an available outbound number.
  • `call_start_time` / `call_end_time`: overall call schedule (`DD/MM/YYYY, HH:mm`).
  • `call_config`: `from_time` and `to_time` are daily window bounds (`HH:mm` matching the API regex), plus `retry_count`, `cooldown_period`, and `time_zone`.
  • `callback_end_time`: when callbacks are allowed until (`DD/MM/YYYY, HH:mm`).
  • `enable_callback`: set to `true` to use callback behavior with `callback_end_time`.
  • `disable_voicemail_retry`: set to `true` to skip retries when voicemail is detected.
  • `custom_variables`: arbitrary JSON object passed into the bot context.

Example JSON body

{
  "call_start_time": "18/10/2025, 09:00",
  "call_end_time": "18/10/2025, 21:05",
  "callback_end_time": "18/10/2025, 21:05",
  "from_number": "+911234567890",
  "is_auto_from_number": true,
  "mobile_number": "+919999999999",
  "call_config": {
    "from_time": "09:00",
    "to_time": "18:00",
    "retry_count": 0,
    "cooldown_period": 0,
    "time_zone": "Asia/Kolkata"
  },
  "chatbot_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "custom_variables": {},
  "enable_callback": true,
  "disable_voicemail_retry": true
}

Next step: get call details

When this call is created successfully, the 200 response returns an id inside data. Copy that value and pass it as the id query parameter on Get Call Details to load the full call record.

  • Example: if the response contains `"id": "${EXAMPLE_CALL_ID}"`, request `GET .../call-details?id=${EXAMPLE_CALL_ID}`.

Open Get Call Details

Goodbox API documentation · Example base URL: https://backend.appzo.ai/v1