Callburn API Documentation NAV Navbar
shell
  • Introduction
  • Callmessages
  • Click To Call
  • Errors
  • Introduction

    Callburn API is designed for making callmessages directly from your website, by connecting to our flexible REST API . For being able to access to our API, you need to send your api key with each request . For obtaining API key go to API section and create a new key . For making development smoothly, we are also giving test API key . It will behave exactly like the live one, just will simulate statuses instead of making real calls and will be free .

    Our API endpoint is https://api.callburn.com/v1/

    Authentication

    Request header example:

    -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Authenticate your account when using the API by including your in the request. You can create your API access key in API Settings also giving permissions to work with exact services in Callburn.

    Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. If you need to authenticate via bearer auth.

    Response example:

        ...
          "links": {
          "first": "https://api.callburn.com/v1/click-to-call/snippets?page=1",
          "last": "https://api.callburn.com/v1/click-to-call/snippets?page=3",
          "prev": null,
          "next": "https://api.callburn.com/v1/click-to-call/snippets?page=2"
          }
          ...
          

    The links object is returned as part of the response body when pagination is enabled.

    By default, 7 objects are returned per page. Even if the response contains 7 objects or fewer, links object will be returned with null value for next and prev.

    You can request a different pagination limit or force pagination by appending ?per_page= to the request with the number of items you would like per page. For instance, to show only two results per page, you could add ?per_page=10 to the end of your query. The maximum number of results per page is 25.

    The values of these are the URLs of the associated pages. The keys will be one of the following:

    Meta

    Response example:

        ...
          "meta": {
          "path": "https://api.callburn.com/v1/click-to-call/snippets",
          "current_page": 1,
          "last_page": 3,
          "from": 1,
          "to": 7,
          "per_page": 7,
          "total": 18
          }
          ...
          

    In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.

    The meta object contains a total key that is set to the total number of objects returned by the request. This has implications on the links object and pagination.

    Currently, the meta object will have a value when a request is made on a collection (like callmessages or click to call snippets).

    Callmessages

    This section is giving ability to control your existing callmessages which you already created in website or through API and you are able to create and delete callmessages through simple API query.

    More info about callmessages you can see in our tutorial

    TTS Languages

    Request example:

        curl "https://api.callburn.com/v1/text-to-speach-languages"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Response example:

        [
          {
          "language": "Arabic",
          "code": "Laila"
          },
          {
          "language": "Arabic",
          "code": "Maged"
          },
          {
          "language": "Arabic",
          "code": "Tarik"
          },
          ...
          ]
          

    This endpoint retrieves all possible Languages to generate audio from text.

    Response Parameters

    Parameter Type Description
    language string Language of voice generation.
    code string Unique identifier which should be sent when want to generate new audio template.

    Audio Templates

    Templates can be created in Audio Templates section as blueprint for messages you’ll send more often.

    Request example:

        curl "https://api.callburn.com/v1/audio-templates?per_page=2"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Response example:

        {
          "data": [
          {
          "token": "f718499c1c8cef6730f9fd03c8125cab2569fb809d740",
          "file": "filename.mp3",
          "tts_text": null,
          "type": "uploaded"
          },
          {
          "token": "59b90e1005a220e2ebc542eb9d950b1e514abc9161c25",
          "file": null,
          "tts_text": "Hi there, we have already opened our new shop in the following address",
          "type": "tts"
          }
          ],
          "links": {
          "first": "https://api.callburn.com/v1/audio-templates?per_page=2&page=1",
          "last": "https://api.callburn.com/v1/audio-templates?per_page=2&page=2",
          "prev": null,
          "next": "https://api.callburn.com/v1/audio-templates?per_page=2&page=2"
          },
          "meta": {
          "current_page": 1,
          "from": 1,
          "last_page": 2,
          "path": "https://api.callburn.com/v1/audio-templates",
          "per_page": 2,
          "to": 2,
          "total": 3
          }
          }
          

    Get Audio Templates List

    This endpoint retrieves paginated existing Audio Templates. You are able to set your own pagination params.

    HTTPS Request

    GET https://api.callburn.com/v1/audio-templates

    Request Parameters

    Parameter Required Default Description
    page No 1 Requested page number in pagination.
    per_page No 7 Limit of items in request (max: 25).

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the snippet.
    file string File name which was uploaded. If file converted from tts_text this value will be null.
    tts_text string Text which was converted to voice file. If audio template was created by uploading file this value will be null
    tts_code string TTS code which was used to convert voice file. If audio template was created by uploading file this value will be null
    type string Should show type of audio template. Could be one of that values uploaded or tts.

    Status of callmessage

    Here is all possible statuses of callmessage item.

    Status Description
    calling_in_progress Means that calling in progress.
    waiting_for_actions Means that callmessage stopped or called but not to all recipients.
    sent Means that callmessage fully sent.
    manually_stopped Means that callmessage manually stopped.
    scheduled Means that callmessage scheduled.
    saved_as_draft Means that callmessage saved as draft.

    Create Callmessage

    This endpoint create new callmessage.

    You can create callmessage using existing audio template by sending audio_template_token which you can get here. Also you can generate new audio template during creating callmessage by sending audio_text and tts_code. All tts_codes you can see here.

    Request example:

        curl "https://api.callburn.com/v1/voice-messages"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
            -H "Content-Type: application/json"
            -d '{
              "name": "My first Callmessage"
              "audio_template_token": "59b90e1005a220e2ebc542eb9d950b1e514abc9161c25",
              "recipients": [
              "+3469*******",
              "+37496******",
              ...
              ],
              "caller_phone_number": "+37491******"
            }'
            -X POST
          

    Response example:

        {
          "token": "6b180037abbebea991d8b1232f8a8ca91013e68ad9633b",
          "name": "My first Callmessage",
          "status": "calling_in_progress"
          }
          

    HTTPS Request

    POST https://api.callburn.com/v1/voice-messages

    Request Parameters

    Parameter Required Type Description
    name No string The human-readable name for the callmessage.
    audio_template_token No string The unique identifier for the audio_template.
    recipients Yes array The phone numbers which must be called, also phone number must be contain country code.
    caller_phone_number Yes string The phone number from which calls will be made. It should be registered in your account settings as caller ID.
    audio_text Yes if is not present audio_template_token string String which will become to audio template.
    tts_code Yes if is not present audio_template_token string This key gives you ability to select voice author, also can see all codes.

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the callmessage.
    name string A human-readable name for the callmessage.
    status string Status of callmessages. Possible statuses here.

    Get Callmessages List

    Request example:

        curl "https://api.callburn.com/v1/voice-messages?per_page=2"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Response example:

        {
          "data": [
          {
          "token": "46444d94f081e3549803b92928260f56100633cc97373c",
          "name": "Schedulation in Progress",
          "status": "calling_in_progress"
          },
          {
          "token": "de51cf91e1e03e51657da1b8c37e33def0012993fb8e91",
          "name": "Stopped callmessage",
          "status": "manually_stopped"
          }
          ],
          "links": {
          "first": "https://api.callburn.com/v1/voice-messages?per_page=2&page=1",
          "last": "https://api.callburn.com/v1/voice-messages?per_page=2&page=4",
          "prev": null,
          "next": "https://api.callburn.com/v1/voice-messages?per_page=2&page=2"
          },
          "meta": {
          "current_page": 1,
          "from": 1,
          "last_page": 4,
          "path": "https://api.callburn.com/v1/voice-messages",
          "per_page": 2,
          "to": 2,
          "total": 7
          }
          }
          

    This endpoint retrieves paginated callmessages. You are able to set your own pagination params.

    HTTPS Request

    GET https://api.callburn.com/v1/voice-messages

    Request Parameters

    Parameter Required Default Description
    page No 1 Requested page number in pagination.
    per_page No 7 Limit of items in request (max: 25).

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the callmessage.
    name string A human-readable name for the callmessage.
    status string Status of callmessages. Possible statuses here.

    Get Single Callmessage

    Request example:

        curl "https://api.callburn.com/v1/voice-messages/46444d94f081e3549803b92928260f56100633cc97373c"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Response example:

        {
          "token": "46444d94f081e3549803b92928260f56100633cc97373c",
          "name": "Schedulation in Progress",
          "status": "calling_in_progress"
          }
          

    This endpoint retrieves single object from callmessages list.

    HTTPS Request

    GET https://api.callburn.com/v1/voice-messages/<TOKEN>

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the callmessage.
    name string A human-readable name for the callmessage.
    status string Status of callmessages. Possible statuses here.

    Delete Single Callmessage

    Request example:

        curl "https://api.callburn.com/v1/voice-messages/46444d94f081e3549803b92928260f56100633cc97373c"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
            -X DELETE
          

    Response example:

        {
          "token": "46444d94f081e3549803b92928260f56100633cc97373c",
          "name": "Schedulation in Progress",
          "status": "calling_in_progress"
          }
          

    This endpoint retrieves single object from callmessages list which already deleted.

    HTTPS Request

    DELETE https://api.callburn.com/v1/voice-messages/<TOKEN>

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the callmessage.
    name string A human-readable name for the callmessage.
    status string Status of callmessages. Possible statuses here.

    Click To Call

    This section is giving ability to control your existing snippets which you already created in website and you are able to make call through simple API query.

    More info about click to call you can see in our tutorial

    Get Snippets List

    Request example:

        curl "https://api.callburn.com/v1/click-to-call/snippets?per_page=2"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
          

    Response example:

        "data": [
          {
          "token": "1UQyEoxj5yHzBbjGadH7MDWaFiQRX6CLBTvb4LkJ",
          "name": "First Snippet Name"
          },
          {
          "token": "7VjSeSgUiDdIVFtee9i2tjYcl585e1h5TbKMGPoB",
          "name": "Other Snippet Name"
          }
          ],
          "links": {
          "first": "https://api.callburn.com/v1/click-to-call/snippets?page=1",
          "last": "https://api.callburn.com/v1/click-to-call/snippets?page=3",
          "prev": null,
          "next": "https://api.callburn.com/v1/click-to-call/snippets?page=2"
          },
          "meta": {
          "current_page": 1,
          "from": 1,
          "last_page": 3,
          "path": "https://api.callburn.com/v1/click-to-call/snippets",
          "per_page": 2,
          "to": 2,
          "total": 5
          }
          

    This endpoint retrieves paginated existing snippets list. You are able to set your own pagination params.

    HTTPS Request

    GET https://api.callburn.com/v1/click-to-call/snippets

    Request Parameters

    Parameter Required Default Description
    page No 1 Requested page number in pagination.
    per_page No 7 Limit of items in request (max: 25).

    Response Parameters

    Parameter Type Description
    token string The unique identifier for the snippet.
    name string A human-readable name for the snippet.

    Make a Call Through Snippet

    Request example:

        curl "https://api.callburn.com/v1/click-to-call/snippets-call"
            -H "Authorization: Bearer ZJ0EtMdds3xYplHVO5OAg8RyYRMG5m9tYoMhjEVb"
            -H "Content-Type: application/json"
            -d '{
              "snippet_token": "59b90e1005...c25",
              "phone_number": "+3469*******",
              "date": "2018-11-30 17:53:00",
              "timezone": "Europe/Rome",
            }'
            -X POST
          

    Response example:

        {
          "code": 200,
          "message": "Your call will be made at 2018-11-30 17:53:00"
          }
          

    You are able to make a call using this URL. Call could be triggered as well as both immediate and scheduled. For scheduled calls you need to sent scheduled call date and timezone of your requested date.

    HTTPS Request

    POST https://api.callburn.com/v1/click-to-call/snippets-call

    Request Parameters

    Parameter Required Type Description
    snippet_token Yes string The unique identifier for the snippet. You can get it in snippets list
    phone_number Yes string The phone number which must be called, also phone number must be contain country code.
    date No Y-m-d H:i:s Time when you want to have a call.
    timezone Only when date requested string Sent timezone in which is your sent date. In PHP you can see all list of possible timezones using this function timezone_identifiers_list().

    Errors

    Response example:

        {
          "code": 400,
          "message": "Out of available date ranges for requested snippet"
          }
          

    The Callburn API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Validation error.
    401 Unauthorized -- Unauthorized request - set in header.
    403 Forbidden -- The requested resource is hidden or not allowed.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access a resource with an invalid method.
    429 Too Many Requests -- You're requesting too many resource! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.