Goodbox

API Reference > Calling

Initiate Individual Call

Create an outbound voice call to a single number. Identify the experience with `chatbot_id`, constrain dialing with `call_config` (window, retries, timezone), and optionally enable callbacks with `callback_end_time`.

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.
  • `call_config`: `from_time` and `to_time` are daily call-window bounds (24h `HH:mm` style strings matching the API regex), `retry_count` and `cooldown_period` control retries, `time_zone` is an IANA or supported zone string.
  • `callback_end_time`: when callbacks are allowed until (example format `DD/MM/YYYY, HH:mm`).
  • `enable_callback`: set to `true` to use callback behavior with `callback_end_time`.
  • `custom_variables`: arbitrary JSON object passed into the bot context.

Example JSON body

{
  "callback_end_time": "18/10/2025, 21:05",
  "from_number": "+911234567890",
  "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
}

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://api.goodbox.ai/ca/api/v1