README

此SDK为用PHP编写的应用程序提供了方便地访问Africa's Talking API的方式。

文档

安装

您可以通过composer或下载源代码来安装PHP SDK。

通过Composer

安装SDK的推荐方式是使用Composer。

composer require africastalking/africastalking

用法

SDK需要使用您的用户名和API密钥进行实例化，您可以从仪表板获取这些信息。

您可以使用此SDK用于生产或沙盒应用程序。对于沙盒，应用程序用户名总是sandbox

use AfricasTalking\SDK\AfricasTalking;

$username = 'YOUR_USERNAME'; // use 'sandbox' for development in the test environment
$apiKey   = 'YOUR_API_KEY'; // use your sandbox app API key for development in the test environment
$AT       = new AfricasTalking($username, $apiKey);

// Get one of the services
$sms      = $AT->sms();

// Use the service
$result   = $sms->send([
    'to'      => '+2XXYYYOOO',
    'message' => 'Hello World!'
]);

print_r($result);

有关更多用法示例，请参阅示例。

实例化

实例化类将为您提供包含可用方法的对象

$AT = new AfricasTalking($username, $apiKey)：实例化类
获取可用服务
- 短信服务：$sms = $AT->sms()
- 内容服务：$content = $AT->content()
- 话费服务：$airtime = $AT->airtime()
- 支付服务：$payments = $AT->payments()
- 语音服务：$voice = $AT->voice()
- 令牌服务：$token = $AT->token()
- 应用程序服务：$application = $AT->application()

应用程序

fetchApplicationData()：获取应用程序信息。例如，余额

话费

send($parameters, $options)：发送话费
- $parameters: 包含以下键的关联数组
  - recipients：包含以下键的数组的数组
    - phoneNumber：话费接收者。 必需
    - currencyCode：3位ISO格式货币代码（例如KES、USD、UGX等）。 必需
    - amount：发送的金额。 必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键

短信

send($options)：发送消息
- message：短信内容。 必需
- to：电话号码数组。 必需
- from：与您的Africa's Talking账户注册的简码或字母数字ID。
- enqueue：如果您希望向API发送尽可能多的消息而不等待来自电信运营商的确认，则将其设置为true。
fetchMessages($options)：获取您的消息
- lastReceivedId：这是您最后处理的消息的ID。默认为0

以下方法已移动到内容服务，但已在短信上保留以实现向后兼容

sendPremium($options)：发送预付费短信。调用$content->send($options)
createSubscription($options)：创建预付费订阅。调用$content->createSubscription($options)
fetchSubscriptions($options)：获取您的预付费订阅数据。调用$content->fetchSubscriptions($options)
deleteSubscription($options)：从高级订阅中删除一个电话号码。调用 $content->$deleteSubscription($options)

内容

send($options)：发送高级短信
- message：短信内容。 必需
- to：电话号码数组。 必需
- from：您在Africa's Talking账户中注册的简码。必需
- keyword：您的高级产品关键词
- linkId：当用户向您的onDemand服务发送消息时，我们转发linkId到您的应用
- retryDurationInHours：“这指定了您的订阅消息在未能成功发送给订阅者时应重试的小时数”
createSubscription($options)：创建高级订阅
- shortCode：映射到您的账户的高级短码。必需
- keyword：在上述短码下的高级关键词，并且也映射到您的账户。必需
- phoneNumber：要订阅的电话号码 必需
- checkoutToken：用于验证订阅请求的令牌 必需。请参阅令牌服务
fetchSubscriptions($options)：获取您的高级订阅数据
- shortCode：映射到您的账户的高级短码。必需
- keyword：在上述短码下的高级关键词，并且也映射到您的账户。必需
- lastReceivedId：您认为的最后一个订阅的ID。默认为 0
deleteSubscription($options)：从高级订阅中删除一个电话号码
- shortCode：映射到您的账户的高级短码。必需
- keyword：在上述短码下的高级关键词，并且也映射到您的账户。必需
- phoneNumber：要订阅的电话号码 必需

支付

mobileCheckout($parameters, $options)：向客户的手机钱包账户收费
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - providerChannel：充电时考虑的提供商通道。
  - phoneNumber：客户电话号码（国际格式）。必需
  - currencyCode：3位ISO格式货币代码（例如KES、USD、UGX等）。 必需
  - amount：要收费的金额。必需
  - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
mobileB2C($parameters, $options)：向客户发送手机钱包
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - recipients：最多10个接收者的列表。每个接收者有
    - phoneNumber：客户电话号码（国际格式）。必需
    - currencyCode：3位ISO格式货币代码（例如KES、USD、UGX等）。 必需
    - amount：要支付的金额。必需
    - reason：支付的目的。请参阅payments::REASON*以获取支持的原因。必需
    - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
mobileB2B($parameters, $options)：向企业（例如银行）发送手机钱包
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - provider：促进此交易的支付提供商。请参阅payments::PROVIDER*以获取支持提供商。必需
  - transferType：描述正在进行的支付类型。请参阅payments::TRANSFER_TYPE*以获取支持的交易类型。必需
  - destinationChannel：将接收付款的提供商名称或号码。必需
  - destinationAccount：企业用于在提供的destinationChannel上接收资金的名称。必需
  - currencyCode：3位ISO格式货币代码（例如KES、USD、UGX等）。 必需
  - amount：要支付的金额。必需
  - requester：当使用B2B购买电力令牌时，KPLC将发送令牌的电话号码。
  - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
mobileData($parameters, $options)：向客户发送移动数据
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - recipients：接收者列表。每个接收者有
    - phoneNumber：客户电话号码（国际格式）。必需
    - quantity：移动数据量。必需
    - unit：移动数据单位。可以是MB或GB。必需
    - validity：移动数据的有效期。必须是Day、Week或Month之一。必需
    - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
bankCheckoutCharge($parameters, $options)：向客户的银行账户收费
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - bankAccount：要收费的银行账户
    - accountName：银行账户名称。必需
    - accountNumber：账户号码。必需
    - bankCode：我们分配的银行 6位整数代码。查看 payments::BANK* 了解支持的银行。 必需
    - dateOfBirth：账户所有者的出生日期（格式为 YYYY-MM-DD）。Zenith Bank Nigeria必需。
  - currencyCode：3位ISO格式货币代码（目前仅支持 NGN）。必需
  - amount：要收费的金额。必需
  - narration：交易简短描述。必需
  - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
bankCheckoutValidate($parameters)：验证银行结账费用
- transactionId：来自银行收费请求返回的交易ID。必需
- otp：您收取的客户提供的单次密码。必需
bankTransfer($parameters, $options)：向银行账户汇款
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - recipients：接收者列表。每个接收者有
    - bankAccount：收款银行账户
      - accountName：银行账户名称。必需
      - accountNumber：账户号码。必需
      - bankCode：我们分配的银行 6位整数代码。查看 payments::BANK* 了解支持的银行。 必需
      - dateOfBirth：账户所有者的出生日期（格式为 YYYY-MM-DD）。Zenith Bank Nigeria必需。
    - currencyCode：3位ISO格式货币代码（目前仅支持 NGN）。必需
    - amount：要支付的金额。必需
    - narration：交易简短描述。必需
    - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
cardCheckoutCharge($parameters, $options)：收取客户的支付卡费用
- $parameters: 包含以下键的关联数组
  - productName：在Africa's Talking上的支付产品。必需
  - paymentCard：要收取费用的支付卡
    - number：支付卡号码。必需
    - cvvNumber：3或4位卡验证值。必需
    - expiryMonth：卡的有效月（例如 8）。必需
    - authToken：支付卡的ATM PIN。必需
    - countryCode：卡发行国家的2位国家代码（目前仅支持 NG）。必需
  - checkoutToken：由我们的API在先前的交易中向客户收取支付卡费用后生成的令牌。当使用 checkoutToken 时，不应填充 paymentCard 数据。
  - currencyCode：3位ISO格式货币代码（目前仅支持 NGN）。必需
  - amount：要收费的金额。必需
  - narration：交易简短描述。必需
  - metadata：与交易关联的附加数据。必需
- $options: 包含以下键的可选关联数组
  - idempotencyKey：用于制作幂等请求的键
cardCheckoutValidate($parameters)：验证卡结账费用
- transactionId：来自卡收费请求返回的交易ID。必需
- otp：您收取的客户提供的单次密码。必需
walletTransfer($parameters)：将资金从一个支付产品转移到另一个支付产品
- productName：在Africa's Talking上的支付产品。必需
- targetProductCode：在Africa's Talking上接收资金的支付产品的唯一代码。必需
- currencyCode：3位ISO格式货币代码。必需
- amount：要转移的金额。必需
- metadata：与交易关联的附加数据。必需
topupStash($parameters)：将资金从一个支付产品转移到应用程序的储备金
- productName：在Africa's Talking上的支付产品。必需
- currencyCode：3位ISO格式货币代码。必需
- amount：要转移的金额。必需
- metadata：与交易关联的附加数据。必需
fetchProductTransactions($parameters)：获取支付产品交易
- productName：在Africa's Talking上的支付产品。必需
- filters：获取交易时使用的筛选器
  - pageNumber：要获取结果的页码。从 1 开始。必需
  - count：要获取的结果数量。必需
  - startDate：获取时要考虑的起始日期。
  - endDate：获取时要考虑的结束日期。
  - category：获取时要考虑的类别。
  - provider：获取时要考虑的提供者。
  - status：获取时要考虑的状态。
  - source：获取时要考虑的来源。
  - destination：获取时要考虑的目的地。
  - providerChannel：获取时要考虑的提供者渠道。
fetchWalletTransactions($parameters)：获取支付钱包交易
- filters：获取交易时使用的筛选器
  - pageNumber：要获取结果的页码。从 1 开始。必需
  - count：要获取的结果数量。必需
  - startDate：获取时要考虑的起始日期。
  - endDate：获取时要考虑的结束日期。
  - categories：获取时要考虑的类别，以逗号分隔的列表。
findTransaction($parameters)：查找特定交易
- transactionId：要查找的交易ID。必需
fetchWalletBalance()：获取您的支付钱包余额

语音

call($options)：发起电话呼叫
- to：您想要拨打的电话号码（使用国际格式）。必需
- from：Africa's Talking上的电话号码（使用国际格式）。必需
fetchQueuedCalls($options)：获取电话号码上的排队呼叫
- phoneNumber: 对应您的 Africa's Talking 账户的电话号码（国际格式）。必需
- name: 获取特定队列的呼叫。
uploadMediaFile($options): 上传语音媒体文件
- phoneNumber: 对应您的 Africa's Talking 账户的电话号码（国际格式）。必需
- url: 要上传的文件的URL。应以http(s)://开头。必需

MessageBuilder

当回调URL收到语音API的POST请求时构建语音xml。可以将操作链式添加以创建XML字符串。

$voiceActions = $voice->messageBuilder();
$xmlresponse = $voiceActions
    ->getDigits($options)
    ->say($text)
    ->record()
    ->build();

say($text): 添加一个 Say 操作
text: 将读给用户的文本（英文）。
play($url): 添加一个 Play 操作
- url: 音频文件的公开URL。此文件将回放给用户。
getDigits($options): 添加一个 GetDigits 操作
- numDigits: 从用户处获取的数字数量
- timeout: 获取用户数字的超时时间（秒）。
- finishOnKey: 用于终止获取数字操作的键。
- callbackUrl: 用于转发获取数字操作结果的URL。
dial($options): 添加一个 Dial 操作
- phoneNumbers: 要拨打的电话号码数组（国际格式）。必需
- record: 布尔值 - 是否要录制对话。
- sequenntial: 布尔值 - 如果提供了多个 phoneNumbers，则确定电话号码是否将依次或同时拨打。
- callerId: 您想要拨出的 Africa's Talking 电话号码。
- ringBackTone: 用户在电话接通前应听到的媒体播放的URL位置。
- maxDuration: 通话的最大时间（秒）。
conference(): 添加一个 Conference 操作
record($options): 添加一个 Record 操作
- finishOnKey: 用于终止录音操作的键。
- maxLength: 录音的最大时间（秒）。
- timeout: 从用户处获取录音的超时时间（秒）。
- trimSilence: 布尔值 - 指定是否要删除录音中用户静默的初始和结束部分。
- playBeep: 布尔值 - 指定API在开始录音时是否应播放蜂鸣声。
- callbackUrl: 用于转发录音操作结果的URL。
enqueue($options): 添加一个 Enqueue 操作
- holdMusic: 用户在等待时播放的文件的URL。
- name: 将通话放入的队列名称。
deqeue($options): 添加一个 Dequeue 操作
- phoneNumber: 用户为加入队列而拨打的对应您的 Africa's Talking 账户的电话号码。必需
- name: 您想要从其中退出的队列名称。
reject(): 添加一个 Reject 操作
redirect($url): 添加一个 Redirect 操作
- url: 转移通话控制的URL。
build(): 在链式某些操作后构建xml

Token

createCheckoutToken($options): 创建一个结账令牌
- phoneNumber: 为其创建结账令牌的电话号码
generateAuthToken(): 生成一个用于认证API请求的认证令牌，而不是您的API密钥。

测试SDK

SDK使用PHPUnit作为测试运行器。

要运行可用的测试，请从项目的根目录运行

# Configure needed fixtures, e.g sandbox api key, Africa's Talking products
cp tests/Fixtures.php.tpl tests/Fixtures.php

# Run tests
phpunit

问题

如果您发现一个错误，请在我们GitHub上的问题跟踪器上提交问题。

appslabke / africastalking

维护者

详细信息