README

本包为使用Laravel编写的应用程序提供了便捷的访问非洲 Talking API 的途径，并且已经与laravel 7进行了测试。

使用本包，您将在Laravel应用程序中获得以下服务
- [短信服务]
- [内容服务]
- [话费服务]
- [支付服务]
- [语音服务]
- [令牌服务]
- [应用程序服务]

文档

安装

您可以通过composer或下载源码来安装此包

通过Composer

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

composer require zepson/africastalking

发布配置文件

php artisan vendor:publish --tag=africastalking_config:config

用法

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

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

use zepson\africastalking\AfricasTalking;

#UPDATE YOUR .ENV FILE WITH YOUR AFRICAS TALKING CREDENTIALS

 add-license-1

AFRICASTALKING_APP_USERNAME = "YOUR AFRICA IS TALKING APP NAME"
AFRICASTALKING_APP_API_KEY = " YOUR APP URL"
AFRICASTALKING_APP_SENDER_ID= ""       // Set your shortCode or senderId
#instantiate your servece as
$AT       = new AfricasTalking();

// 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(): 实例化类
获取可用服务
- 短信服务: $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: 与您的非洲 Talking 账户注册的简码或字母数字ID。
- enqueue: 设置为 true，如果您希望向API发送尽可能多的消息而不等待电信运营商的确认。
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：企业在提供的目的地渠道上接收资金的名称。 必需
  - currencyCode: 3位ISO格式货币代码（例如 KES、USD、UGX 等）。 必需
  - amount：要支付的金额。 必需
  - requester：通过该电话号码，KPLC 在使用 B2B 购买电力令牌时发送令牌。
  - 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: 在非洲的Taling上接收资金的支付产品的唯一代码。必填
- 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：转发 GetDigits 操作结果的 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：转发 Recording 操作结果的 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 请求的 auth 令牌，而不是您的 API 密钥。

zepson / africastalking

维护者

详细信息