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


Video explaining the feature:






Availability - Beta


As we continue to build new products and features in order to serve our customers better, we release new products in beta and it’s a great way for you to integrate this solution to take early advantage and improve the capabilities of your system.


What is beta?


Products that are released under beta are new solutions/features that we continue to build/tweak based on feedback from customers and closely monitor for issues. This is to ensure that such newly launched products meet the high-quality standard of Exotel general availability guidelines.

There might be modifications during the beta phase, and the final version of the release can vary from beta. However, any non-compatible change or major modifications which can impact the users shall be communicated to the customers.


Support for beta release
If you have any questions or concerns, please connect with us using the chat widget on your Exotel Dashboard or Whatsapp us on 08088919888.


However, since these products are in beta, the time taken to respond to some of the queries or issues may be longer as it will be directly handled by our product and engineering teams and not covered by our standard support SLAs.