Create an outbound campaign

A campaign calls one or more contacts while giving the bot shared context and row-specific data. It is also the public API entry point for requesting a one-off call with a bot.

Prepare the file

Use an Excel or CSV file with a header row. One column must contain the telephone number. Other columns can provide a name, reference, amount or any data useful to the scenario.

Include only information required for the call. Through the API, you can provide the same list directly in the JSON contacts array without creating a file.

Create the campaign

1. Name the campaign and choose the bot.
2. Describe the shared objective.
3. Import the file, then select the telephone number column.
4. Map the other columns to labels the bot can understand.
5. Select the required campaign type: direct marketing, marketing with explicit consent, or transactional.
6. Set the date, pacing and maximum number of concurrent calls.
7. If an external system must be notified, enter its HTTPS URL under Completion notification.
8. Save as draft or schedule it.

When the call is answered, the bot systematically leaves the first spoken turn to the callee: it waits for “hello”, “yes” or another utterance before running its introduction prompt. If nobody speaks for five seconds, the runtime exceptionally releases the introduction to avoid an endless silence. This technical instruction applies equally to campaigns created in the interface, through the public API, and to test calls.

Start a one-off call through the API

The public API does not provide a direct /api/v1/outbound-calls route. To call one contact, create a campaign with one entry and schedule it in the same request:

POST /api/v1/outbound-campaigns
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "name": "One-off call CRM-12345",
  "bot_id": 42,
  "prompt": "Contact the customer about case CRM-12345.",
  "campaign_type": "transactional",
  "schedule": true,
  "max_concurrent_calls": 1,
  "contacts": [
    {
      "phone": "+32470123456",
      "name": "Marie Dupont",
      "case_id": "CRM-12345"
    }
  ]
}

With schedule: true, omitting scheduled_at requests a start as soon as capacity, credit and applicable checks allow. To schedule the call, provide a future ISO 8601 timestamp such as 2026-09-03T09:30:00+02:00. With schedule: false, the campaign remains a draft and can later be started with POST /api/v1/outbound-campaigns/{id}/start.

The 201 response contains data.id for the campaign and data.calls[].id for each call. Monitor an individual call with GET /api/v1/outbound-campaigns/calls/{call_id}. Terminal states are completed, failed and cancelled; scheduled, claimed and dialing still indicate ongoing processing.

Use transactional for a call related to an existing relationship or operation. The marketing_direct type applies DNCM screening. The marketing_consent type requires consent_evidence_acknowledged: true and assumes that the organisation retains evidence of explicit consent.

Receive the completion notification

The webhook is optional. BeAI calls it asynchronously once all campaign contacts have reached a final state. A temporary failure triggers several retries.

The notification is deliberately minimal: it contains the outbound_campaign.completed event, the campaign identifier, the completed status, a delivery identifier and the GET /api/v1/outbound-campaigns/{id} route. It contains no contact details, transcript or detailed result. The receiving system can use its own BeAI API key to retrieve only the information it is authorised to access.

Make a test call

Use Test call to enter your number and representative values for each column. The test checks the prompt and behaviour without launching the full list.

The API equivalent is POST /api/v1/outbound-campaigns/{id}/test-call. It therefore requires an existing campaign, reuses its bot, prompt, mapping and type, and returns a call in the same format as the monitoring route. The test call remains subject to applicable checks and costs, but is excluded from campaign counters and progress.

Control pacing

The selected number remains subject to the global server limit and your SIP operator's limits. A campaign configured for three concurrent calls may progress more slowly if other calls already use the available capacity.

DNCM control

For direct marketing, BeAI checks the number against the DNCM list. A recent cached decision is used first, then the official API when required. If the API is unavailable and no local decision exists, the call may proceed in degraded mode and the decision is logged.

Monitor and reuse

Open the pre-filtered conversations from the campaign. You can remove or edit eligible contacts, duplicate a campaign to reuse its context with a new file, and restart a campaign using the available actions.

When the bot's Recording skill is enabled, outbound calls are recorded in the same way as inbound calls. The audio file appears in the conversation detail after the call is finalised.