# AfricasTalking Client SDK

> Provides convenient access to the Africa's Talking Voice APIs from your web apps.

## Documentation
Take a look at the [API docs here](https://build.at-labs.io/docs/voice/overview).

  
## Install

### NPM (Recommended)
You can install the package from [npm](npmjs.com/package/africastalking-client) by running: 

```bash
$ npm install --save africastalking-client
```
You can import the method like so:

```javascript
import Africastalking from 'africastalking-client'
```

### CDN
The SDK is also accessible via our hosted cdn which can be included into your web page using the `<script>` tag 

```html
<script src="https://unpkg.com/africastalking-client@1.0.6/build/africastalking.js"></script>
```
You can access the global variable `Africastalking` from your browser.

## Capability Token
You need to instantiate your client with a capability token.
It is generated by making an API POST request from to `https://webrtc.africastalking.com/capability-token/request` with the following parameters:

### Request Parameters
> NB: API requests require an `apiKey` in your request header for authentication.

| Parameters   |      Description         |
|----------|------------------|
| username<br>`String`<br>`Required` | Your Africa’s Talking application username |
| clientName<br>`String`<br>`Required` | Your unique name used to identify and call your browser client(without space characters) |
| phoneNumber<br>`String`<br>`Required` | Your Africa’s Talking phone number (in international format i.e. +254XXXYYY) |
| incoming<br>`Boolean`<br>`Optional` | Enable the client to recieve incoming calls. Defaults to `true` |
| outgoing<br>`Boolean`<br>`Optional` | Enable the client to make outgoing calls. Defaults to `true` |
| expire<br>`String`<br>`Optional` | Period of time it takes the token to expire, in seconds. Default is `86400s` |


### API Response
```json
{
    "clientName": "somsom",
    "incoming": true,
    "lifeTimeSec": "86400",
    "outgoing": true,
    "token": "ATCAPtkn_206675b68efaff83d1ac2d027dd5bff18fd7cb64fgjhd5d0bdcsac44a883678afe7"
}
```

## Usage
You can then initialize the client using the token. 
```javascript
const client = new Africastalking.Client(token)
```

### Events
```javascript
client.on('incomingcall', function (params) {
    alert(`${params.from} is calling you`)
}, false);

client.on('hangup', function (hangupCause) {
    alert(`Call hung up (${hangupCause.code} - ${hangupCause.reason})`)
}, false);
```
#### Event Types
| Events   |      Description         |
|----------|------------------|
| `ready` | Client is ready to make or recieve calls |
| `notready` | Client cant make or recieve calls, |
| `calling` | Your client is making a call |
| `incomingcall` | Your client is recieving a call |
| `callaccepted` | Call has been accepted |
| `hangup` | Call has ended |
| `offline` | Token has expired |
| `closed` | Connection to africastalking servers closed |


### Methods
```javascript
$("button").click(function() { 
    client.call("+254XXXXXYYY"); 
}); 

$("button").click(function() { 
    client.dtmf("1"); 
}); 

$("button").click(function() { 
    client.muteAudio(); 
}); 
```

#### Client Methods
| methods   |      Description         |
|----------|------------------|
| `call` | Make a call to a phone number or browser client |
| `answer` | Answer a call |
| `hangup` | End an ongoing call |
| `dtmf` | pass dtmf digits to Africastalking API<br> |
| `muteAudio` | Disables audio media sent during a call<br> |
| `unmuteAudio` | Enable audio media sent during a call<br> |
| `hold` | Puts a call on-hold <br> |
| `unhold` | Resumes a call <br> |