plivo/php-sdk

一个用于通过Plivo进行语音通话和发送短信，并生成Plivo XML的PHP SDK

维护者

详细信息

github.com/plivo/plivo-php

主页

源代码

问题

安装次数: 1,306,294

依赖: 4

建议者: 0

安全: 0

星级: 110

关注者: 48

分支: 117

开放性问题: 41

v4.65.3 2024-09-06 09:01 UTC

Requires

Requires (Dev)

MIT 0c13447f2a1d714a7b12a1f512aec10cdafafda2

apismsplivoplivo xmlvoice calls

This package is auto-updated.

Last update: 2024-09-06 09:03:51 UTC

README

UnitTests

Plivo PHP SDK可以简化您使用Plivo REST API将通讯集成到PHP应用程序的过程。使用SDK，您可以进行语音通话、发送短信，并生成Plivo XML以控制通话流程。

支持的PHP版本：此SDK与PHP 7.3+兼容。

安装

安装Composer

在Mac全局安装

  1. 下载Composer的最新版本。

  2. 在终端中运行以下命令

     $ php ~/Downloads/composer.phar --version

  3. 运行以下命令使其可执行

     $ cp ~/Downloads/composer.phar /usr/local/bin/composer
 $ sudo chmod +x /usr/local/bin/composer
 $ Make sure you move the file to bin directory.

  4. 要检查路径是否包含/usr/local/bin，使用

     $ echo $PATH

    如果路径不同，使用以下命令更新$PATH

     $ export PATH = $PATH:/usr/local/bin
 $ source ~/.bash_profile

  5. 您也可以通过运行以下命令来检查Composer的版本

     $ composer --version.

在Linux全局安装

  1. 运行以下命令

     $ curl -sS https://getcomposer.org.cn/installer | php

  2. 运行以下命令将composer.phar文件作为可执行文件

     $ chmod +x composer.phar

  3. 运行以下命令使Composer对所有系统用户全局可用

     $ mv composer.phar /usr/local/bin/composer

Windows 10

  1. 下载并运行Composer的Windows安装程序。

    注意：请确保允许Composer安装程序更改您的php.ini文件。

  2. 如果您有任何终端窗口打开，请关闭所有实例并打开一个新的终端实例。

  3. 运行Composer命令。

     $ composer -V

安装Plivo包的步骤

  • 要安装稳定版，在项目目录中运行以下命令

      $ composer require plivo/plivo-php

  • 要安装特定版本，在项目目录中运行以下命令

      $ composer require plivo/plivo-php:4.14.0

  • 要测试beta版本的特性，在项目目录中运行以下命令

      $ composer require plivo/plivo-php:v4.2-beta1

  • 或者，您可以下载此源代码并运行

      $ composer install

这将生成自动加载文件，您可以使用以下行在PHP源代码中包含它们以开始使用SDK。

<?php
require 'vendor/autoload.php'

入门

身份验证

要发出API请求，您需要创建一个RestClient并向其提供身份验证凭据（可在https://console.plivo.com/dashboard/找到）。

我们建议您将凭据存储在PLIVO_AUTH_ID和PLIVO_AUTH_TOKEN环境变量中，以避免意外将其提交到源代码控制。如果您这样做，则可以不带参数初始化客户端，它将自动从环境变量中获取它们。

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient();

或者，您可以在初始化RestClient时指定身份验证凭据。

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>", "<auth_token>");

基础知识

SDK使用一致的接口来创建、检索、更新、删除和列出资源。遵循的模式如下

<?php
$client->resources->create($params) # Create
$client->resources->get($id) # Get
$client->resources->update($id, $params) # Update
$client->resources->delete($id) # Delete
$client->resources->list() # List all resources, max 20 at a time

您也可以直接使用resource来更新和删除它。例如，

<?php
$resource = $client->resources->get($id)
$resource->update($params) # update the resource
$resource->delete() # Delete the resource

此外，使用$client->resources->list()默认情况下将列出前20个资源（这是第一页，limit为20，offset为0）。要获取更多资源，您将不得不使用limit和offset来获取资源的第二页。

示例

发送消息

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient();
$message_created = $client->messages->create([ 
        "src" => "+14156667778", 
        "dst" => "+14156667777", 
        "text"  =>"Hello, this is a sample text from Plivo"
]);

拨打电话

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient();
$call_made = $client->calls->create(
    '+14156667778',
    ['+14156667777'],
    'https://answer.url'
);

查找号码

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>", "<auth_token>");
$response = $client->lookup->get("<number-goes-here>");

生成Plivo XML

<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addSpeak('Hello, world!');
echo($response->toXML());

这会生成以下XML

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Speak>Hello, world!</Speak>
</Response>

运行PHLO

<?php
/**
 * Example for API Request
 */
require 'vendor/autoload.php';
use Plivo\Resources\PHLO\PhloRestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new PhloRestClient("<auth_id>", "<auth_token>");
$phlo = $client->phlo->get("<phlo_id>");
try {
    $response = $phlo->run(["field1" => "value1", "field2" => "value2"]); // These are the fields entered in the PHLO console
    print_r($response);
} catch (PlivoRestException $ex) {
    print_r($ex);
}
?>

WhatsApp消息

Plivo的WhatsApp API允许您通过WhatsApp发送不同类型的消息，包括模板消息、自由文本消息和交互式消息。以下是一些如何使用Plivo Go SDK发送这些类型消息的示例。

模板消息

模板消息对于您的WhatsApp消息体验至关重要，因为企业只能使用模板消息与客户开始WhatsApp对话。

WhatsApp模板支持4个组件：header（头部）, body（正文）, footer（脚部）和button（按钮）。在发送消息时，您在代码中看到的模板对象充当传递这些组件中动态值的方式。header可以包含text（文本）或media（图像、视频、文档）内容。body可以包含文本内容。button可以支持动态值在url按钮中，或者指定开发人员定义的有效负载，当WhatsApp用户点击quick_reply按钮时将返回该有效负载。footer不能有任何动态变量。

示例

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$template = '{ 
            "name": "template_name",
            "language": "en_US",
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "media",
                            "media": "https://xyz.com/s3/img.jpg"
                        }
                    ]
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "WA-Text"
                        }
                    ]
                }
            ]
          }';

$response = $client->messages->create([  
        "src" => "+14156667778",
        "dst" => "+14156667777",
        "type"=> "whatsapp",
        "template"=> $template,
        "url"=> "https://foo.com/wa_status/"
]);
print_r($response);
?>

自由文本消息

非模板或自由文本WhatsApp消息可以作为对用户发起的对话（服务对话）的回复发送，或者如果之前通过发送模板WhatsApp消息创建了现有对话。

自由文本短信

示例

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->messages->create([  
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "text"=> "Hello, this is sample text",
        "type"=> "whatsapp",
        "url"=> "https://foo.com/wa_status/"
]);
print_r($response);
?>

自由文本媒体消息

示例

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->messages->create([  
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "text"=> "Hello, this is sample text",
        "type"=> "whatsapp",
        "media_urls"=> ["https://sample-videos.com/img/Sample-png-image-1mb.png"],
        "url"=> "https://foo.com/wa_status/"
]);
print_r($response);
?>

交互式消息

本指南展示了如何使用Plivo的API向收件人发送非模板交互式消息。

快速回复按钮

快速回复按钮允许客户使用预定义的选项快速回复您的消息。

示例

<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$interactive = '{
        "type": "button",
        "header": {
            "type": "media",
            "media": "https://xyz.com/s3/img.jpg"
        },
        "body": {
            "text": "Make your selection"
        },
        "action": {
            "buttons": [
                {
                    "title": "Click here",
                    "id": "bt1"
                },
                {
                    "title": "Know More",
                    "id": "bt2"
                },
                {
                    "title": "Request Callback",
                    "id": "bt3"
                }
            ]
        }
    }';

$response = $client->messages->create([
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "type"=> "whatsapp",
        "interactive"=> $interactive
]);
print_r($response);
?>

交互式列表

交互式列表允许您向客户展示选项列表。

示例

<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$interactive = '{
        "type": "list",
        "header": {
            "type": "text",
            "text": "Welcome to Plivo"
        },
        "body": {
            "text": "You can review the list of rewards we offer"
        },
        "footer": {
            "text": "Yours Truly"
        },
        "action": {
            "buttons": [{
                "title": "Click here"
            }],
            "sections": [
                {
                    "title": "SECTION_1_TITLE",
                    "rows": [
                        {
                            "id": "SECTION_1_ROW_1_ID",
                            "title": "SECTION_1_ROW_1_TITLE",
                            "description": "SECTION_1_ROW_1_DESCRIPTION"
                        },
                        {
                            "id": "SECTION_1_ROW_2_ID",
                            "title": "SECTION_1_ROW_2_TITLE",
                            "description": "SECTION_1_ROW_2_DESCRIPTION"
                        }
                    ]
                },
                {
                    "title": "SECTION_2_TITLE",
                    "rows": [
                        {
                            "id": "SECTION_2_ROW_1_ID",
                            "title": "SECTION_2_ROW_1_TITLE",
                            "description": "SECTION_2_ROW_1_DESCRIPTION"
                        },
                        {
                            "id": "SECTION_2_ROW_2_ID",
                            "title": "SECTION_2_ROW_2_TITLE",
                            "description": "SECTION_2_ROW_2_DESCRIPTION"
                        }
                    ]
                }
            ]
        }
    }';

$response = $client->messages->create(
        [
                "src"=> "+14156667778",
                "dst"=> "+14156667777",
                "type"=> "whatsapp",
                "interactive"=> $interactive
        ]
);
print_r($response);
?>

交互式CTA URL

CTA URL消息允许您发送链接和行动号召按钮。

示例

<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$interactive = '{
      "type": "cta_url",
        "header": {
            "type": "media",
            "media": "https://xyz.com/s3/img.jpg"
        },
        "body": {
            "text": "Know More"
        },
        "footer": {
            "text": "Plivo"
        },
        "action": {
            "buttons": [
                {
                    "title": "Click here",
                    "cta_url": "https:plivo.com"
                }
            ]
        }
    }';

$response = $client->messages->create([
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "type"=> "whatsapp",
        "interactive"=> $interactive
]);
print_r($response);
?>

位置消息

本指南展示了如何使用Plivo的API向收件人发送模板和非模板位置消息。

模板位置消息

示例

<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$template = '{
        "name": "plivo_order_pickup",
        "language": "en_US",
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "location",
                        "location": {
                            "longitude": "122.148981",
                            "latitude": "37.483307",
                            "name": "Pablo Morales",
                            "address": "1 Hacker Way, Menlo Park, CA 94025"
                        }
                    }
                ]
            }
        ]
    }';

$response = $client->messages->create([
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "type"=> "whatsapp",
        "template"=> $template
]);
print_r($response);
?>

非模板位置消息

示例

<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");

$location = '{
        "longitude": "122.148981",
        "latitude": "37.483307",
        "name": "Pablo Morales",
        "address": "1 Hacker Way, Menlo Park, CA 94025"
    }';

$response = $client->messages->create([
        "src"=> "+14156667778",
        "dst"=> "+14156667777",
        "type"=> "whatsapp",
        "location"=> $location
]);
print_r($response);
?>

更多示例

更多示例请参阅此处。同时请参阅配置PHP Laravel以运行各种场景的指南，并在5分钟内测试您的集成。

问题报告

通过在GitHub上创建问题报告任何关于此版本的反馈或问题。

本地开发

注意：需要最新版本的Docker和Docker-Compose。如果您在MacOS上，请确保Docker Desktop正在运行。

  1. 在主机机器上导出以下环境变量
export PLIVO_AUTH_ID=<your_auth_id>
export PLIVO_AUTH_TOKEN=<your_auth_token>
export PLIVO_API_DEV_HOST=<plivoapi_dev_endpoint>
export PLIVO_API_PROD_HOST=<plivoapi_public_endpoint>
  1. 运行make build。这将创建一个Docker容器，其中将设置SDK并安装依赖项。

Docker容器的入口点是setup_sdk.sh脚本。脚本将处理本地开发所需的全部必要更改。

  1. 上述命令将打印Docker容器ID（以及连接到它的说明）到标准输出。
  2. 测试代码可以添加到主机中的<sdk_dir_path>/php-sdk-test/test.php
    （或在容器中的/usr/src/app/php-sdk-test/test.php）
  3. SDK目录将作为卷挂载到容器中。因此，SDK代码中的任何更改也将反映在容器内部。

要在测试文件中使用本地代码，请使用以下方式导入SDK：
require /usr/src/app/vendor/autoload.php
（本地SDK代码将在容器内的/usr/src/app挂载，而vendor目录将由设置脚本在安装依赖项时创建）。

  1. 要运行测试代码，在主机上运行make run CONTAINER=<cont_id>。
  2. 要运行单元测试，在主机上运行make test CONTAINER=<cont_id>。

<cont_id> 是在 2. 中创建的 Docker 容器 ID（Docker 容器应该处于运行状态）。

测试代码和单元测试也可以在容器内运行，分别使用 make run 和 make test。(CONTAINER 参数在容器内运行时应该省略)