africastalking-ts
Version:
Unofficial Typescript version of the Africa's Talking SDK
1,109 lines (855 loc) • 31.9 kB
Markdown
# SDK Reference
## Contents
- [What can I import from the SDK?](#What-can-i-import-from-the-sdk)
- [Initializing a Client](#initializing-a-client)
- [Client Functions](#client-functions)
## What can I import from the SDK?
You can import the following functions, classes and Typescript types from the SDK:
- Client
- ActionBuilder (for Voice)
- CONSTANTS (for Payments)
- Types for Typescript e.g. `SmsResponse`, `SendAirtimeResponse`, etc.
```ts
import { Client, ActionBuilder, CONSTANTS, SmsResponse, SendAirtimeResponse } from 'africastalking-ts';
// or
const { Client, ActionBuilder, CONSTANTS, SmsResponse, SendAirtimeResponse } = require('africastalking-ts').
```
### Notes
- All functions are asynchronous.
- All phone numbers use the international format. e.g. `+254xxxxxxxx`.
## Initializing a Client
You need your app username and your API key to create a new Africa's Talking Client, both of which you can get from the [dashboard](https://account/africastalking.com).
> You can use this SDK for either production or sandbox apps. For sandbox, the app username is **ALWAYS** `sandbox`
```javascript
import { Client } from 'africastalking-ts'; // const { Client } = require('africastalking-ts');
const client = new Client({
apiKey: 'YOUR_API_KEY', // you can get this from the dashboard: https://account.africastalking.com
username: 'YOUR_USERNAME', // use 'sandbox' as the value for development in the test environment
});
```
## Client Functions
- [Airtime Operations](#airtime-operations)
- sendAirtimeRequest
- [Application Operations](#application-operations)
- fetchApplicationData
- [Chat Operations](#chat-operations)
- sendChatOptIn
- sendChatTemplateMessage
- sendChatTextMessage
- sendChatMediaMessage
- sendChatLocationMessage
- [Payments Operations](#payments-operations)
- topupStash
- walletTransfer
[bank](#bank)
- bankCheckoutCharge
- bankCheckoutValidate
- bankTransfer
[card](#card)
- cardCheckoutCharge
- cardCheckoutValidate
[mobile](#mobile)
- mobileB2B
- mobileB2C
- mobileCheckout
- mobileData
[query](#query)
- fetchProductTransactions
- fetchWalletBalance
- fetchWalletTransactions
- findTransaction
- [SMS Operations](#sms-operations)
- fetchMessages
- sendSms
- sendPremiumSms
[premium subscriptions](#premium-subscriptions)
- createSubscription
- deleteSubscription
- fetchSubscription
- [Token Operations](#token-operations)
- createCheckoutToken
- generateAuthToken
- [Voice Operations](#voice-operations)
- getNumQueuedCalls
- makeCall
- uploadMediaFile
## Airtime Operations
- ### sendAirtimeRequest({ recipients })
Send airtime to a bunch of phone numbers.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| recipients | _array, REQUIRED_ | An array of objects containing the recipients. |
Each _recipient_ in the array is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| phoneNumber | _string, REQUIRED_ | The recipient's phone number. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to charge. |
For more information, please read [http://docs.africastalking.com/airtime/sending](http://docs.africastalking.com/airtime/sending).
#### Example
```ts
client.sendAirtimeRequest({
recipients: [
{
phoneNumber: '+254711111111',
currencyCode: 'KES',
amount: 10,
},
],
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
## Application Operations
- ### fetchApplicationData()
Get app information. e.g. balance.
For more information, please read [http://docs.africastalking.com/userdata/balance](http://docs.africastalking.com/userdata/balance).
#### Example
```ts
client.fetchApplicationData()
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
## Chat Operations
- ### sendChatOptIn({ from, to, action })
Send an Opt In request to a Whatsapp phone number.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| from | _string, REQUIRED_ | The channel number, e.g. +254711111111. |
| to | _string, REQUIRED_ | The customer number, e.g. +254711111111. |
| action | _string, REQUIRED_ | The type of action. Can be `OptIn` or `OptOut`. |
#### Example
```ts
client.sendChatOptIn({
from: '+254711111111',
to: '+254711111111',
action: 'OptIn',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendChatTemplateMessage({ productId, from, to, template })
Send a Template Message to a Whatsapp phone number.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productId | _string, REQUIRED_ | The product id, e.g. titan-ltd. |
| from | _string, REQUIRED_ | The channel number, e.g. +254711111111. |
| to | _string, REQUIRED_ | The customer number, e.g. +254711111111. |
| template | _object, REQUIRED_ | The template to be used. See format below. |
`template` is of the following format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| name | _name, REQUIRED_ | The name of the WhatsApp template to use. This must be approved by WhatsApp. |
| params | _array of strings, REQUIRED_ | Parameters to use to substitute into the WhatsApp template message. |
#### Example
```ts
client.sendChatTemplateMessage({
productId: 'titan-ltd',
from: '+254711111111',
to: '+254711111111',
template: {
name: 'lorem',
params: ['john', 'doe', 10, 5],
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendChatTextMessage({ productId, channel, from, to, message })
Send a Text Message to a Whatsapp phone number or Telegram chat.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productId | _string, REQUIRED_ | The product id, e.g. titan-ltd. |
| channel | _string, REQUIRED_ | Can be either `whatsapp` or `telegram`. |
| from | _string, REQUIRED_ | The channel number, e.g. +254711111111. |
| to | _string, REQUIRED_ | The customer number, e.g. +254711111111. |
| message | _string, REQUIRED_ | The message to be sent. |
#### Example 1: Whatsapp
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'whatsapp',
from: '+254711111111',
to: '+254711111111',
message: 'Hello world',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
#### Example 2: Telegram
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'telegram',
from: 'titan_ltd_bot',
to: '987654321',
message: 'Hello world',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendChatMediaMessage({ productId, channel, from, to, type, url, caption })
Send a Media Message to a Whatsapp phone number or Telegram chat.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productId | _string, REQUIRED_ | The product id, e.g. titan-ltd. |
| channel | _string, REQUIRED_ | Can be either `whatsapp` or `telegram`. |
| from | _string, REQUIRED_ | The channel number, e.g. +254711111111. |
| to | _string, REQUIRED_ | The customer number, e.g. +254711111111. |
| type | _string, REQUIRED_ | Can be `image`, `video`, `audio`, `document`, `voice`, or `sticker`. |
| url | _string, REQUIRED_ | The file url. |
| caption | _string, OPTIONAL_ | A caption for the media file. |
#### Example 1: Whatsapp
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'whatsapp',
from: '+254711111111',
to: '+254711111111',
type: 'image',
url: 'https://www.fonewalls.com/wp-content/uploads/1536x2048-Background-HD-Wallpaper-213.jpg',
caption: 'Hello world',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
#### Example 2: Telegram
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'telegram',
from: 'titan_ltd_bot',
to: '987654321',
type: 'image',
url: 'https://www.fonewalls.com/wp-content/uploads/1536x2048-Background-HD-Wallpaper-213.jpg',
caption: 'Hello world',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendChatLocationMessage({ productId, channel, from, to, lat, lng })
Send a Location Message to a Whatsapp phone number or Telegram chat.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productId | _string, REQUIRED_ | The product id, e.g. titan-ltd. |
| channel | _string, REQUIRED_ | Can be either `whatsapp` or `telegram`. |
| from | _string, REQUIRED_ | The channel number, e.g. +254711111111. |
| to | _string, REQUIRED_ | The customer number, e.g. +254711111111. |
| lat | _string, REQUIRED_ | The latitude which should be between -90 and +90. |
| lng | _string, REQUIRED_ | The longitude which should be between -180 and +180 |
#### Example 1: Whatsapp
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'whatsapp',
from: '+254711111111',
to: '+254711111111',
lat: 1.2,
lng: -5.224,
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
#### Example 2: Telegram
```ts
client.sendChatTextMessage({
productId: 'titan-ltd',
channel: 'telegram',
from: 'titan_ltd_bot',
to: '987654321',
lat: 1.2,
lng: -5.224,
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
## Payments Operations
- ### topupStash({ productName, currencyCode, amount, metadata })
Move money from a Payment Product to an app's stash.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| metadata | _object_ | Additional info to go with the transfer. |
#### Example
```ts
client.walletTransfer({
productName: 'TestProduct',
currencyCode: 'KES',
amount: 50,
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
});
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### walletTransfer({ productName, targetProductCode, currencyCode, amount, metadata })
Move money form one payment product to another.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| targetProductCode | _string, REQUIRED_ | ID of recipient payment product on Africa's Talking. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| metadata | _object_ | Additional info to go with the transfer. |
#### Example
```ts
client.walletTransfer({
productName: 'TestProduct',
targetProductCode: 3323,
currencyCode: 'KES',
amount: 50,
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
});
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
### bank
- ### bankCheckoutCharge({ productName, bankAccount, currencyCode, amount, narration, metadata })
Initiate a bank checkout.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| bankAccount | _object, REQUIRED_ | Bank account to charge. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| narration | _string, REQUIRED_ | Checkout description. |
| metadata | _object_ | Additional info to go with the transfer. |
#### Example
```ts
import { CONSTANTS } from 'africastalking-ts';
client.bankCheckoutCharge({
productName: 'TestProduct',
bankAccount: {
accountName: 'Test Bank Account',
accountNumber: '1234567890',
bankCode: CONSTANTS.BANK.FCMB_NG,
},
currencyCode: 'KES',
amount: 50,
narration: 'Test Payment',
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### bankCheckoutValidate({ transactionId, otp })
Validate a bank checkout.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| transactionId | _string, REQUIRED_ | Transaction ID returned on charge request. |
| otp | _string, REQUIRED_ | A user-provided OTP. |
#### Example
```ts
client.bankCheckoutValidate({
transactionId: 'ATPid_SampleTxnId1',
otp: '1234',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### bankTransfer({ productName, recipients })
Initiate a bank transfer.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| recipients | _array, REQUIRED_ | A list of banks to transfer to. |
Each recipient in the array is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| bankAccount | _object, REQUIRED_ | Bank account to charge. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| narration | _string, REQUIRED_ | Checkout description. |
| metadata | _object_ | Additional info to go with the transfer. |
The `bankAccount` is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| accountName | _string, REQUIRED_ | The name of the bank account. |
| accountNumber | _string, REQUIRED_ | The bank account number. |
| bankCode | _number, REQUIRED_ | The bank code. |
| dateOfBirth | _string, REQUIRED_ | The date of birth. |
#### Example
```ts
import { CONSTANTS } from 'africastalking-ts';
client.bankTransfer({
productName: 'TestProduct',
recipients: [{
bankAccount: {
accountName: 'Test Bank Account',
accountNumber: '1234567890',
bankCode: CONSTANTS.BANK.FCMB_NG,
},
currencyCode: 'KES',
amount: 50,
narration: 'Test Payment',
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
}],
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
### card
- ### cardCheckoutCharge({ productName, paymentCard, checkoutToken, currencyCode, amount, narration, metadata })
Initiate a card checkout.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| paymentCard | _object, REQUIRED_ (if `checkoutToken` is not provided) | Card to charge. |
| checkoutToken | _string, REQUIRED_ (if `paymentCard` is not provided) | Token from a previous successful transaction. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| narration | _string, REQUIRED_ | Checkout description. |
| metadata | _object_ | Additional info to go with the transfer. |
`paymentCard` is of the following format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| number | _string, REQUIRED_ | Payment card number. |
| cvvNumber | _object, REQUIRED_ | 3 or 4 digit payment card verification value. |
| expiryMonth | _number, REQUIRED_ | Expiration month on the payment card. |
| expiryYear | _number, REQUIRED_ | Expiration year on the payment card. |
| countryCode | _string, REQUIRED_ | 2-Digit country code where the payment card was issued. _Only “NG” is currently supported_ |
| authToken | _string, REQUIRED_ | The payment cards ATM PIN. |
#### Example
```ts
client.cardCheckoutCharge({
productName: 'TestProduct',
paymentCard: {
number: '123456789000',
cvvNumber: 654,
expiryMonth: 7,
expiryYear: 2025,
authToken: '2345',
countryCode: 'NG',
},
currencyCode: 'NGX',
amount: 50,
narration: 'Test Payment',
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### cardCheckoutValidate()
Validate a card checkout.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| transactionId | _string, REQUIRED_ | Transaction ID returned on charge request. |
| otp | _string, REQUIRED_ | A user-provided OTP. |
#### Example
```ts
client.cardCheckoutValidate({
transactionId: 'ATPid_SampleTxnId1',
otp: '1234',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
### mobile
- ### mobileB2B({ productName, provider, transferType, currencyCode, amount, destinationChannel, destinationAccount, metadata })
Send mobile money to business.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| provider | _string, REQUIRED_ | Provider used to process request. |
| transferType | _string, REQUIRED_ | Transfer type of the payment. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to transfer. |
| destinationChannel | _string, REQUIRED_ | Name or number of channel to receive payment. |
| destinationAccount | _string, REQUIRED_ | Account name used to receive money. |
| metadata | _object, REQUIRED_ | Additional info to go with the transfer. |
#### Example
```ts
import { CONSTANTS } from 'africastalking-ts';
client.mobileB2B({
productName: 'TestProduct',
provider: CONSTANTS.PROVIDER.ATHENA,
transferType: CONSTANTS.TRANSFER_TYPE.B2B_TRANSFER,
currencyCode: 'KES',
amount: 100,
destinationChannel: '456789',
destinationAccount: 'octopus',
metadata: { notes: 'Account top-up for July 2017' },
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### mobileB2C({ productName, recipients })
Send mobile money to consumer.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| recipients | _array, REQUIRED_ | A list of consumers that will receive the money. |
Each _recipient_ in the array is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| name | _string_ | The recipient's name. |
| phoneNumber | _string, REQUIRED_ | The recipient's phone number. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to charge. |
| providerChannel | _string, REQUIRED_ | The channel the payment will be made from e.g a paybill number. |
| reason | _string, REQUIRED_ | Purpose of the payment. |
| metadata | _object, REQUIRED_ | Additional info to go with the transfer. |
#### Example
```ts
import { CONSTANTS } from 'africastalking-ts';
client.mobileB2C({
productName: 'TestProduct',
recipients: [
{
phoneNumber: '254711111111',
currencyCode: 'KES',
reason: CONSTANTS.REASON.SALARY,
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
amount: 234.5,
},
],
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### mobileCheckout({ productName, providerChannel, phoneNumber, currencyCode, amount, metadata })
Initiate mobile checkout.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| providerChannel | _string_ | Provider channel to consider when charging. |
| phoneNumber | _string, REQUIRED_ | The recipient's phone number. |
| currencyCode | _string, REQUIRED_ | 3-digit ISO format currency code. |
| amount | _number, REQUIRED_ | Amount to charge. |
| metadata | _object, REQUIRED_ | Additional info to go with the transfer. |
#### Example
```ts
client.mobileCheckout({
productName: 'TestProduct',
phoneNumber: '+254711111111',
currencyCode: 'KES',
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
amount: 234.5,
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### mobileData({ productName, recipients })
Send mobile data to customers.
#### Parameters
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| recipients | _array, REQUIRED_ | A list of consumers that will receive the money. |
Each _recipient_ in the array is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| phoneNumber | _string, REQUIRED_ | The recipient's phone number. |
| quantity | _number, REQUIRED_ | Mobile data amount. |
| unit | _string, REQUIRED_ | Mobile data unit. Can either be `MB` or `GB`. |
| validity | _string, REQUIRED_ | How long the mobile data is valid for. Must be one of `Day`, `Week` and `Month`. |
| metadata | _object, REQUIRED_ | Additional info to go with the transfer. |
#### Example
```ts
client.mobileData({
productName: 'TestProduct',
recipients: [{
phoneNumber: '+254711223344',
quantity: 10,
unit: 'GB',
validity: 'Month',
metadata: {
id: '088930432excvmklevdf',
name: 'John Doe',
},
}],
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
### query
- ### fetchProductTransactions({ productName, filters })
Fetch payment product transactions.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| productName | _string, REQUIRED_ | Your payment product. |
| filters | _object, REQUIRED_ | Query filters. |
_filters_ is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| pageNumber | _string, REQUIRED_ | Page number to fetch results from. Starts from `'1'`. |
| count | _string, REQUIRED_ | Number of results to fetch. |
| startDate | _string_ | Start Date to consider when fetching. |
| endDate | _string_ | End Date to consider when fetching. |
| category | _string_ | Category to consider when fetching. |
| provider | _string_ | Provider to consider when fetching. |
| status | _string_ | Status to consider when fetching. |
| source | _string_ | Source to consider when fetching. |
| destination | _string_ | Destination to consider when fetching. |
| providerChannel | _string_ | Provider channel to consider when fetching. |
#### Example
```ts
client.fetchProductTransactions({
productName: 'TestProduct',
filters: {
pageNumber: '1',
count: '10',
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### fetchWalletBalance()
Fetch your wallet's balance
#### Example
```ts
client.fetchWalletBalance()
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### fetchWalletTransactions({ filters })
Fetch wallet transactions.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| filters | _object, REQUIRED_ | Query filters. |
_filters_ is of the format:
| Param | Type | Description |
| :------- | :------------ | :------------ |
| pageNumber | _string, REQUIRED_ | Page number to fetch results from. Starts from `'1'`. |
| count | _string, REQUIRED_ | Number of results to fetch. |
| startDate | _string_ | Start Date to consider when fetching. |
| endDate | _string_ | End Date to consider when fetching. |
| categories | _string_ | Category to consider when fetching. |
#### Example
```ts
client.fetchWalletTransactions({
filters: {
pageNumber: '1',
count: '10',
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### findTransaction({ transactionId })
Find a particular transaction.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| transactionId | _string, REQUIRED_ | Transaction ID returned on charge request. |
#### Example
```ts
client.findTransaction({
transactionId: 'ATPid_SampleTxnId1',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
For more information, please read [http://docs.africastalking.com/payments](http://docs.africastalking.com/payments).
## SMS Operations
- ### fetchMessages({ lastReceivedId })
Manually retrieve your messages.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| lastReceivedId | _string, REQUIRED_ | This is the id of the message that you last processed. Defaults to `'0'`. |
#### Example
```ts
client.fetchMessages()
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendSms({ to, message, from, enqueue })
Send a message.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| to | _string, REQUIRED_ | Recipients phone number. |
| message | _string, REQUIRED_ | SMS content. |
| from | _string_ |Shortcode or alphanumeric ID that is registered with Africa's Talking account. |
| enqueue | _string_ | Set to true if you would like to deliver as many messages to the API without waiting for an acknowledgement from telcos. |
#### Example
```ts
client.sendSms({
to: '+254711111111',
message: 'This is a test',
enqueue: true,
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### sendPremiumSms({ to, message, from, enqueue, keyword, linkId, retryDurationInHours })
Send premium SMS.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| to | _string, REQUIRED_ | Recipients phone number. |
| message | _string, REQUIRED_ | SMS content. |
| from | _string_ |Shortcode or alphanumeric ID that is registered with Africa's Talking account. |
| enqueue | _string_ | Set to true if you would like to deliver as many messages to the API without waiting for an acknowledgement from telcos. |
| keyword | _string_ | Your premium product keyword. |
| linkId | _string_ | We forward the linkId to your application when the user send a message to your service. |
| retryDurationInHours | _string_ | It specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber. |
#### Example
```ts
client.sendPremiumSms({
to: '+254718760882',
from: 'testService',
message: 'This is premium test',
keyword: 'test',
linkId: '76test',
retryDurationInHours: 1,
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
### premium subscriptions
- ### createSubscription({ shortCode, keyword, phoneNumber, checkoutToken })
Create a premium subscription.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| shortCode | _string, REQUIRED_ | This is the premium short code mapped to your account. |
| keyword | _string, REQUIRED_ | A premium keyword under the above short code and mapped to your account. |
| phoneNumber | _string, REQUIRED_ | The phone number to be subscribed. |
| checkoutToken | _string, REQUIRED_ | This is a token used to validate the subscription request. |
#### Example
```ts
client.createSubscription({
shortCode: '1234',
keyword: 'TESTKWD',
phoneNumber: '+254711111111',
checkoutToken: '12abvsfdhh63535',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### deleteSubscription({ shortCode, keyword, phoneNumber })
Deletes a premium subscription.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| shortCode | _string, REQUIRED_ | This is the premium short code mapped to your account. |
| keyword | _string, REQUIRED_ | A premium keyword under the above short code and mapped to your account. |
| phoneNumber | _string, REQUIRED_ | The phone number to be subscribed. |
#### Example
```ts
client.deleteSubscription({
shortCode: '1234',
keyword: 'TESTKWD',
phoneNumber: '+254711111111',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### fetchSubscription({ shortCode, keyword, lastReceivedId })
Fetches premium subscriptions.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| shortCode | _string, REQUIRED_ | This is the premium short code mapped to your account. |
| keyword | _string, REQUIRED_ | A premium keyword under the above short code and mapped to your account. |
| lastReceivedId | _number_ | ID of the subscription you believe to be your last. Set it to `0` to for the first time. |
#### Example
```ts
client.fetchSubscription({
shortCode: '1234',
keyword: 'TESTKWD',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
For more information, please read:
- SMS service: [http://docs.africastalking.com/sms](http://docs.africastalking.com/sms)
- How to fetch subscriptions: [http://docs.africastalking.com/subscriptions/fetchsubscriptions](http://docs.africastalking.com/subscriptions/fetchsubscriptions)
- How to listen for subscription notifications: [http://docs.africastalking.com/subscriptions/callback](http://docs.africastalking.com/subscriptions/callback)
## Token Operations
- ### createCheckoutToken(phoneNumber)
Create a new checkout token.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| shortCode | _string, REQUIRED_ | The phone number you want to create a subscription for. |
#### Example
```ts
client.createCheckoutToken('+254711111111')
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### generateAuthToken()
Generate an auth token to use for authentication instead of an API key.
#### Example
```ts
client.generateAuthToken()
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
## Voice Operations
- ### getNumQueuedCalls({ phoneNumbers })
Get queued calls.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| phoneNumbers | _string, REQUIRED_ | Your Africa's Talking issued virtual phone number. |
#### Example
```ts
client.getNumQueuedCalls({
phoneNumbers: '254711111111'
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### makeCall({ callFrom, callTo, clientRequestId })
Initiate a phone call.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| callFrom | _string, REQUIRED_ | Your Africa's Talking issued virtual phone number. |
| callTo | _string, REQUIRED_ | Phone number to dial. |
| clientRequestId | _string_ | Variable sent to your Events Callback URL that can be used to tag the call. |
#### Example
```ts
client.makeCall({
callFrom: '+254711111111',
callTo: ['+254711111111', '+254722222222'],
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
- ### uploadMediaFile({ url })
Upload voice media file.
| Param | Type | Description |
| :------- | :------------ | :------------ |
| url | _string, REQUIRED_ | The url of the file to upload. Don’t forget to start with `http://`. |
#### Example
```ts
client.uploadMediaFile({
url: 'http://google.com',
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
```
For more information, please read [http://docs.africastalking.com/voice](http://docs.africastalking.com/voice).