How does the Campaigns API work
3 min
Before you start a Call Campaign, set a clear objective. We have some use cases here and guidelines here. Based on the business objective, configure a call flow. Campaigns API attempts to make calls to comma-separated ‘From’ numbers specified in the request. When a call is picked up, the flow is executed and status reported. A Campaign schedule determines when to start and end the campaign. Retry logic determines how and when to attempt to call a phone number again in case of failure.
To use Campaigns API, including sample code, please refer to our developer portal
Below are some important considerations to keep in mind while using the API.
- When a request has an invalid number, then the entire request is failed with the number available in the failure message.
- The request will fail on the first invalid number found, the rest of the data is not processed. The developer is encouraged to use the phone number lib to validate his data before sending it.
- Terminal states of a campaign are ‘completed’, ‘failed’, ’deleted’, and 'canceled'. Intermediate states are 'created' , 'in-progress' and 'paused'.
- Campaign States (intermediate)
- created - A campaign API request that was successfully accepted by the system.
- in-progress - A campaign that has started.
- paused - A campaign, that was scheduled was requested to be paused explicitly.
- Campaign States (Terminal):
- failed - None of the calls were made (5xx /4xx / invalid numbers) for all of the phone numbers for the campaign. Immediate failures are marked as failed as well with the HTTP status code reflecting the reason for failure.
- completed - all / partial calls (where the end time was reached) were made successfully.
- canceled - A campaign was ‘paused’ but was not resumed ever and end_at was reached is marked as canceled. All the remaining calls for the campaign are marked as failed.
- deleted - A campaign can be marked deleted only if it has not started.
- Call status
- in-progress - When the call is triggered
- failed - no retry was allowed and the status was ‘no-answer’, ‘busy’ or ‘failed’ state
- completed - When this call was ‘completed’ by Exotel
- CustomFields are part of the report. CustomFields value is applicable to all numbers uniformly.
- Campaigns are marked as ‘failed’ if all calls were not attempted. If all calls were attempted, then that call campaign is successful, however, the status of individual calls will determine the success/failure of each call.
- A call to a number that failed (including retries) is marked as “failed”
- DELETE is possible only on campaigns that have not yet started.
- A campaign that is in progress, the below fields can be updated
- Callbacks
- Action
- When end_at is specified, Exotel makes its best effort to ensure that calls are completed within that period but is not guaranteed. POST request with end_at will return 200 OK irrespective of whether all calls can be made or not. All numbers that were not called because of timer expiry will be marked as ‘canceled’
- The report captures numbers that were not dialed for a failed campaign as well
- Long-Running Campaigns:
- A cut-off time, 10.30 am - 9 pm is provisioned, which will imply that no call is made beyond the cut-off time.
- Paused campaigns without an end time specified will expire after 30 days from the start_at time.
- Throttle limits - 200 API requests per min with 60 concurrent channels
Watch a short video