README

Take Blip WhatsApp API 通知的 PHP SDK

要求

• PHP >= 8.1

描述

Take Blip 通知 WhatsApp API 的 PHP SDK。

安装

通过 Composer

composer require vitorccs/takeblip-php

参数

如何使用

1. 参数可以通过环境变量定义

putenv('TAKEBLIP_API_KEY=myApiKey');
putenv('TAKEBLIP_API_TIMEOUT=20');

或作为实例参数传递

new \TakeBlip\TakeBlip($token, $timeout);

1. 然后，只需请求端点

$takeBlip = new \TakeBlip\TakeBlip();

// Obter Templates de Mensagens 
$response = $takeBlip->getMessageTemplates();

// Obter Identificador do usuário (altere este número)
$response = $takeBlip->getUserIdentity('551190000000');

// Enviar Notificação Ativa
$takeBlip->sendNotification($pictureTemplate);

// Consultar os eventos da Notificação disparada
$takeBlip->getNotificationEvents('myNotificationId');

错误处理

该库抛出以下异常

• HttpClientException 用于 HTTP 4xx 错误
• HttpServerException 用于 HTTP 5xx 错误

重要：由于 Take Blip API 总是返回 HTTP 2xx（成功）代码，即使操作未成功，因此实现了检查响应体的处理，如果发现“failure”值，则抛出 HttpClientException 类型的异常。

响应体示例

{
    "method": "get",
    "status": "failure",
    "reason": {
        "code": 61,
        "description": "The string supplied did not seem to be a phone number."
    }
}

实现示例

error_reporting(E_ALL);
ini_set('display_errors', 1);

require __DIR__.'/vendor/autoload.php';

putenv('TAKEBLIP_API_KEY=myApiKey');

use TakeBlip\Exceptions\HttpClientException;
use TakeBlip\Exceptions\HttpServerException;

try {
    $takeBlip = new \TakeBlip\TakeBlip();
    
    # Step 1/4 - Obter Identificador do usuário
    $response = $takeBlip->getUserIdentity('551190000000');
    $userIdentity = $response->resource->identity;
        
    # Step 2/4 - Construir o Template da Mensagem
    $builder = new \TakeBlip\Builders\TemplateBuilder();
    $template = $builder
        ->create('user_identity',
            'my_template_name',
            'my_template_namespace')
        ->addVariable('MyVar1')
        ->addVariable('MyVar2')
        ->addReply('QuickReply1')
        ->addReply('QuickReply2')
        ->setUrl('https://www.domain.com/boleto.pdf', 'document', 'BoletoBancario.pdf')
        ->get();
            
    # Step 3/4 - Enviar Notificação Ativa
    $takeBlip->sendNotification($template);
    
    # Step 4/4 - Consultar os eventos da Notificação (opcional)
    // Esta consulta não deveria ser feita imediatamente após o disparo
    // e os eventos podem levar vários minutos para chegarem
    sleep(5); // apenas para fins de teste
    $response = $takeBlip->getNotificationEvents($template->id);
    print_r($response);
   
} catch (HttpClientException $e) { // erros de cliente (HTTP 4xx)
    echo sprintf('Client: %s (%s)', $e->getMessage(), $e->getHttpCode());
} catch (HttpServerException $e) { // erros de servidor (HTTP 5xx)
    echo sprintf('Server: %s (%s)', $e->getMessage(), $e->getHttpCode());
} catch (\Exception $e) { // demais erros
    echo $e->getMessage();
}

警告

消息模板需要与 WhatsApp 上批准的模板一致。

为了减少错误风险，实现了模板构造函数 TemplateBuilder。

然而，它无法识别某些错误

• Identity、模板名称或命名空间数据无效
• 模板具有 URL 但未提供或存在故障
• 变量或快速回复的数量不正确
• 在模板不包含 URL、变量或快速回复的情况下定义 URL、变量或快速回复

上述错误目前无法在 Take Blip API 发射时检测到，将作为成功（HTTP 2xx）发射。只能通过查询端点 getNotificationEvents 来识别。

测试

如果想要贡献，请实现 PHPUnit 的单元测试。

执行

1. 将 phpunit.xml.dist 复制到项目根目录下的 phpunit.xml
2. 在项目目录的终端中执行以下命令

composer test

附件

• Take Blip WhatsApp 通知教程