Documentation

Below you will find information on how to use the 46elks API. Don't hesitate to contact us if you have any questions!

• Introduction

• Phone numbers

• SMS messages

• Voice calls

• IVRs & recording

•  

• History

• Subaccounts

•  

• Sample code

• FAQ

Introduction

The 46elks cloud API enables your applications to use telephony technology in a simple manner. With this API you can do things such as send and receive SMS messages, control incoming phone calls, build IVRs, connect calls and create automated outgoing phone calls.

Basics

The base URL for this API is https://api.46elks.com/a1/ and it is based upon common REST principles. Basic HTTP authentication is used for access control, and you can find your API credidentials at https://dashboard.46elks.com/

Request data is sent as regular POST-variables. Responses from the API is in JSON format. In case of an error, you will receive a 403 Forbidden or 404 Not found reply. Error descriptions are sent as plain text in the HTTP content.

Phone numbers

For anything other than just sending SMS, you need one or more 46elks phone numbers. You can either allocate phone numbers manually within the dashbord or using the API.

Number allocation

To allocate a new 46elks phone number make a POST request to the resource /Numbers. The variable "country" is mandatory, while "sms_url" and "voice_start" are optional.

POST /a1/Numbers

The response when allocating a new number looks like below, and is exactly the same as when you query a number previously allocated:

GET /a1/Numbers/n57c8f48af76bf986a14f251b35389e8b

Modification and deallocation

For incoming SMS messages, the attribute "sms_url" on your numbers is used. And for incoming Voice calls, "voice_start" it what you are looking for. If you ever need to change these, either do it manually in the dashboard or use the API and simply do a POST like this:

POST /a1/Numbers/n57c8f48af76bf986a14f251b35389e8b

You can also deallocate one of your numbers by setting "active" to "no". Beware that there is no way to get your number back once it has been deallocated.

46elks credits will be consumed at time of allocation and each new month until deallocated.

SMS messages

Receiving SMS

Whenever there is an incoming SMS to one of your allocated mobile phone numbers we will make a request to your chosen "sms_url" with the following POST-variables:

POST http://myservice.se/callback/newsms.php

Delivery to your "sms_url" will be retried for 24 hours until a HTTP 200 OK response is received.

Replying to a received SMS

If you want to reply an incoming SMS, just send your reply as text in the HTTP response when your "sms_url" is being requested and it will be sent back to the originating mobile phone. SMS message texts are always encoded in UTF-8.

Sending SMS

To send a new SMS simply POST to the /SMS resource. The "from" number can either be one of your previously allocated mobile phone numbers or an arbitrary alphanumeric string of at most 11 characters.

POST /a1/SMS

When using an alphanumeric "from", you are restricted to a-z, A-Z, and 0-9 and max 11 characters. No other characters can be used, and the name has to begin with a letter. Upon request, we can also unlock other "from" numbers for your account.

Sending batches of SMS

It is possible to send the same message to multiple recipients in one API call. Do this by specifying multiple mobile numbers as "to" separated by comma (,). The limit of recipients in one single API call is 2000.

POST /a1/SMS

Beware - the whole batch sending will fail if you pass in numbers which are not proper E.164.

Message lengths

Splitting and joining multi-part SMS messages are automatically handled by the API.

Flash SMS

For some use cases you just want to show a message directly to the mobile phone user, in a more alerted way, and without storing it in the mobile phones history. This mobile network features is commonly called Flash SMS. You can send such SMS messages with the 46elks platform by setting the POST variable "flashsms" to "yes" when sending SMS.

Check this blog post to see how a Flash SMS looks like recevied on an iPhone.

Delivery reports

Optional delivery reports allow you to track invidual SMS messages you send, to find out if the have reached the destination. To activate delivery reports simply add your callback URL to the POST variable "whendelivered" when you send an SMS.

Whenever we have new delivery information regarding your SMS, we will make a POST request to your URL with the following:

POST http://myservice.se/callback/dlr.php

Beware that some destinations and mobile networks does not support delivery reports. Thus, the "status" of SMS messages you send to such destinations will at most stop at "sent".

Voice calls

Incoming calls

Incoming calls are controlled by the "voice_start" attribute on your phone number. The URL you put there will be requested every time there is a new incoming call.

If your "voice_start" contains a JSON object, that action will be triggered directly when incoming calls are received, without making any requests to your web server.

Voice actions

A phone call in 46elks is basically a set of actions and results. Each action is a JSON object explaining what you want to do. And by reading the results you control the flow of actions and ultimately reach the end of the call.

Hands on example

{
  "connect":"+46704508449"
}

If you use the above JSON as voice_start for an incoming call, it will connect the call to the swedish cell phone number 070-450 84 49 and upon answer allow the two callers to speak to each other.

Action chaining

To make something happen after an action is finished or when an action has a certain result, there are specific JSON keys you can define. Each action has it's own possible results, but most actions have the "next" result key, which indicate "continue here regardless of result".

Values for result keys can either be a new action object, or a URL string telling 46elks where to fetch action(s) from. URLs are retrieved with HTTP POST.

{
  "connect":"+46704508449",
  "busy":{
    "connect":"+46731704032"
  }
}

POST variables

The following variables are always included in the requests to your URLs. For completed actions, the variable "result" is also included.

Action - "connect"

Initiate an outgoing call to given number, and in the case of an answer, let the two callers speak to each other.

Possible results:

Limitations:
Calls to mobile 46elks numbers can only "connect" to same-country mobile numbers.

Action - "hangup"

End the call. If this is your first action, it is possible to control signalling, otherwise only "reject" is allowed.

Action - "play"

Play the given sound, which could be either a URL on your server or a sound resource provided by 46elks. URLs are fetched using HTTP GET and are always cached, so for unique resources be sure to provide unique URLs.

The plattform currently supports WAV, MP3 and OGG Vorbis.

{
  "play": "http://myserver.se/welcome.wav",
  "next": {
    "connect":"+46704508449",
    "busy":{
      "connect":"+46731704032"
    }
  }
}

For a successful "play" action, the result will be "next". In case the resource or URL fails to load, the action result will be "failed".

If the caller presses a digit during "play", the call directly continues at "next".

Sound resources and DTMF

Some builtin sound resources are provided by 46elks, such as beeps and DTMF tones. These are:

• sound/beep
• sound/dtmf/123 (or any DTMF digit sequence you would like to play, up to 30 digits)

If you need to add some pause between DTMF tones, use p for one or more short 50ms pauses or the capital letter P for longer 500ms pauses.

There are also sound resources specific to a certain call. This is currently limited to recordings (read below), and all those resources are prefixed with "local", such as "local/recording1".

Action - "ivr"

The "ivr" action fills the purpose of playing a sound resource, while also retrieving digits punched by the caller. If no digits are retrieved after playback + 10 seconds of wait, the sound resource will be repeated up to 3 times. You can change the repeat count using the "repeat" key, and how many seconds to wait for input can be changed with the "timeout" key.

By default, the action is completed directly when a single digit has been received. If you want to allow input of more digits, use the "digits" key.

The result of this action is the digits retrieved.

{
  "ivr": "http://myserver.se/menu.wav",
  "1": {
    "play": "http://myserver.se/one.wav"
  },
  "2": {
    "play": "http://myserver.se/two.wav"
  }
}

Can I receive the pressed digits?

Yes, instead of coding the options within the JSON you can instruct the 46elks platform to pass the pressed digits to your script, regardless of what the caller press. Simply set the key "next" to your URL.

{
  "ivr": "http://myserver.se/enterpin.wav",
  "digits": 5,
  "next": "http://myserver.se/login.php"
}

You will get the digits pressed in the "result" POST variable.

Action - "record"

Record the voice of the caller with this action. Useful for building your own voicemail. By default, recording stops after 3 seconds of silence or when 2 minutes of voice has been recorded.

Control the timelimit by adding an integer to the key "timelimit. Specified in seconds.

The recording can be saved either directly to a URL of your choice, or stored in the platform locally to allow playback before saving the recording. Set "record" to "local/recording1" if you want to allow playback within the same call. All local recordings are discarded when the call ends.

{
  "play": "http://myserver.se/entervoicemail.wav",
  "next": {
    "record": "http://myserver.se/newvoicemail.php"
  }
}

POST http://myserver.se/newvoicemail.php

When does an incoming call end?

Either when your action chain is empty, or when the caller has hangup. Execution of the action chain will not continue in the case of caller hangup, simply because then there is no longer any call to control.

Call recording

With 46elks, you can record the full contents of both incoming and outgoing calls.

Option - "recordcall"

At any level within your tree of voice actions, you can put the key "recordcall". When reaching that depth in your JSON tree, the call will start to be recorded.

{
  "play": "http://myserver.se/connecting.wav",
  "next": {
    "connect": "+46704508449",
    "recordcall": "http://myserver.se/newrecording.php"
  }
}

The value for your "recordcall" should be a URL, and this URL will be POSTed when the call has ended and the recording is done (much like how action "record" works).

Outgoing calls

To create an outgoing call, simply POST to the /Calls resource. This will instruct 46elks to automatically call the number you have selected.

When the dialed number answers, the call will continue according to the "voice_start" argument of the POST.

POST /a1/Calls

How can I track unanswered outgoing calls?

Use the "whenhangup" variable if you want to be able to track calls which are never answered, such as busy or failed outgoing calls. This URL will be POST-requested when the call is hangup, either by failure to connect or after a connected call was finished and hangup.

SMS & calls history

You can list the SMS messages you have sent and recevied with a simple GET to /SMS. The same can be done for calls, by accessing the /Calls resource.

By default you get the 100 latest items.

GET /a1/SMS

{
  "data": [
    {
      "id": "s17a6dafb12d6b1cabc053d57dac2b9d8",
      "created": "2012-03-14T09:52:07.302000",
      "direction": "outgoing",
      "from": "MyService",
      "to": "+46704508449",
      "message": "Hello hello",
      "status": "delivered",
      "delivered": "2012-03-14T09:52:10Z",
      "cost": 3500
    },
    {
      "id": "s299b2d2a467945f59e1c9ea431eed9d8",
      "created": "2012-03-14T08:44:34.608000",
      "direction": "outgoing-reply",
      "from": "+46766861069",
      "to": "+46704508449",
      "message": "We are open until 19:00 today. Welcome!",
      "status": "delivered",
      "delivered": "2012-03-14T08:44:36Z",
      "cost": 3500
    },
    {
      "id": "s292d2a459e967945fb1c9ea431eed9d8"
      "created": "2012-03-14T08:44:34.135000",
      "direction": "incoming",
      "from": "+46704508449",
      "to": "+46766861069",
      "message": "Hours?",
      "cost": 3500
    }
  ],
  "next": "2012-02-21T14:15:30.427000"
}

The response is in JSON format. The key "data" contains a list of the items you requested. There is also a key named "next", which can be used to older history. Do this by by adding a "start" argument to your GET request, set to the value of your last "next".

GET /a1/SMS?start=2012-02-21T14:15:30.42700

{
  "data": [
    {
      "id": "s053d57dac2b9d894a6dafb12d6b1ca12",
      "created": "2012-02-21T14:15:30.427000",
      "direction": "outgoing",
      "from": "TestElk",
      "to": "+46704508449",
      "message": "One two three testing",
      "status": "delivered",
      "delivered": "2012-02-21T14:15:34Z",
      "cost": 3500
    }
  ]
}

This way you can fetch your full SMS & Calls history if needed.

Subaccounts

Are many different customers using the services you have built using 46elks? Subaccounts allow you to separate your different customers within the 46elks platform. Subaccounts have their own 46elks numbers and traffic history, isolated from other subaccounts.

As expected, subaccounts use 46elks credits from your main 46elks account.

Adding a subaccount

In order to create a new subaccount, simply make an HTTP POST to the /Subaccounts resource. The only mandatory key when creating a new subaccount is the key "name".

POST /a1/Subaccounts

{
  "id": "a123457da5678d894a6dafb1212b1ca12",
  "secret": "A347215F5F799B814462C37694D2383D",
  "name": "Sample Customer AB",
  "balanceused": 0
}

Using a subaccount

The keys "id" and "secret" is the new API username and API password you should use in order to access the 46elks API for this subaccount. Use these API credentials when you want to make API requests for the subaccount.

Subaccounts are isolated from each other, and there is no way for a subaccount to access information about the main account. It is thus possible to safely deploy the subaccount credentials to a customers server or application.

Can I limit how much credits a subaccount can use?

Yes, make an HTTP POST to the specific subaccount's resource and set "usagelimit" to the requested value. Once this is set and "balanaceused" reach "usagelimit", credit consumption for this subaccount will be denied

POST /a1/Subaccounts/a123457da5678d894a6dafb1212b1ca12

{
  "id": "a123457da5678d894a6dafb1212b1ca12",
  "secret": "A347215F5F799B814462C37694D2383D",
  "name": "Sample Customers New Name AB",
  "balanceused": 7000,
  "usagelimit": 200000
}