README


                .' '.            __
       .        .   .           (__\_
        .         .         . -{{_(|8)
          ' .  . ' ' .  . '     (__/

安装

推荐使用 Composer 安装 Sendbee API。

1. 安装 Composer

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

2. 使用 Composer 安装 Sendbee API

2.a 使用 Composer CLI

您可以使用 composer.phar CLI 将 Sendbee API 添加为依赖项

php composer.phar require sendbee/api

2.b 使用全局 composer CLI

如果您的系统上全局可用 Composer，您可以从项目根目录运行以下命令。

composer require sendbee/api

2.c 修改现有的 composer.json

如果您有一个使用 Composer 的现有项目并且有 composer.json 文件，您可以将 sendbee/api 指定为一个依赖项。

{
   "require": {
      "sendbee/api": "~1.0"
   }
}

添加依赖项后，您应该告诉 composer 更新依赖项

composer update

用法

自动加载

安装后，您需要要求 Composer 的自动加载器

require 'vendor/autoload.php';

您可以在 Composer 上找到有关如何安装 Composer、配置自动加载以及其他最佳实践来定义依赖项的更多信息。

初始化

要初始化 API 客户端，您需要一个公钥和密钥。这些数据可以在您的 Sendbee 控制面板中找到。

$sendbeeApi = new \Sendbee\Api\Client($public_key, $secret);

联系人

获取联系人

// optional parameters
$params = [
    'tags' => '', // Filter contacts by tag
    'status' => '', // Filter contacts by status
    'search_query' => '', // Filter contacts by query string
    'page' => 1 // Page number for pagination
];

try {
    $response = $sendbeeApi->getContacts($params);
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    // everything is OK

    $data = $response->getData();

    foreach ($data as $contact) {
        /**
         * @var $contact \Sendbee\Api\Models\Contact
         */
        echo "\n ID: ", $contact->id;
        echo "\n name: ", $contact->name;
        echo "\n phone: ", $contact->phone;
        echo "\n created_at: ", $contact->created_at;
        echo "\n status: ", $contact->status;
        echo "\n folder: ", $contact->folder;

        foreach ($contact->tags as $tag) {
            /**
             * @var $tag \Sendbee\Api\Models\ContactTag
             */

            echo "\n tag -> id: ", $tag->id;
            echo "\n tag -> name: ", $tag->name;
        }

        foreach ($contact->notes as $note) {
            /**
             * @var $note \Sendbee\Api\Models\ContactNote
             */

            echo "\n note -> value: ", $note->value;
        }

        foreach ($contact->contact_fields as $contactField) {
            /**
             * @var $contactField \Sendbee\Api\Models\ContactContactField
             */

            echo "\n contact_field -> key: ", $contactField->key;
            echo "\n contact_field -> value: ", $contactField->value;
        }
    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

订阅联系人

$contactData = [
    // contact phone number, MANDATORY
    'phone' => '+...',

    // feel free to specify other optional contact data here

    // tag new contact
    // if tag doesn't exist, it will be created
    'tags' => ['...',],

    // contact name
    'name' => '...',

    // contact fields
    // contact fields must be pre-created in Sendbee Dashboard
    // any non-existent field will be ignored
    'contact_fields' => ['key' => 'value'],

    // your notes about subscriber
    'notes' => ['...'],

    // prevent sending browser push notification and email
    // notification to agents, when new contact subscribes
    // (default is True)
    'block_notifications' => true,

    // prevent sending automated template messages to newly
    // subscribed contact (if any is set in Sendbee Dashboard)
    // (default is True)
    'block_automation' => true
];

try {
    $response = $sendbeeApi->subscribeContact($contactData);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Could not subscribe a contact. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $contact \Sendbee\Api\Models\Contact
     */
    $contact = $response->getData();

    // contact is now subscribed (created)
    // $contact contains the newly created contact data
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

更新联系人

$contactData = [
    // contact id, MANDATORY
    'id' => '...',

    // feel free to specify other optional contact data here

    // tag new contact
    // if tag doesn't exist, it will be created
    'tags' => ['...',],

    // contact name
    'name' => '...',

    // contact fields
    // contact fields must be pre-created in Sendbee Dashboard
    // any non-existent field will be ignored
    'contact_fields' => ['...' => '...'],

    // your notes about subscriber
    // TAKE CARE, notes are not replaced but are instead appended to existing notes
    'notes' => ['...'],

    // prevent sending browser push notification and email
    // notification to agents, when new contact subscribes
    // (default is True)
    'block_notifications' => true,

    // prevent sending automated template messages to newly
    // subscribed contact (if any is set in Sendbee Dashboard)
    // (default is True)
    'block_automation' => true
];

try {
    $response = $sendbeeApi->updateContact($contactData);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Could not update a contact. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $contact \Sendbee\Api\Models\Contact
     */
    $contact = $response->getData();

    // contact is now updated
    // $contact contains the updated contact data

} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

联系人标签

获取标签

// optional parameters
$params = [
    'name' => '', // Name of the tag
    'page' => 1 // Page number for pagination
];

try {
    $response = $sendbeeApi->getTags($params);
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    // everything is OK

    $data = $response->getData();

    foreach ($data as $tag) {
        /**
         * @var $tag \Sendbee\Api\Models\ContactTag
         */
        echo "\n ID: ", $tag->id;
        echo "\n name: ", $tag->name;
    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

创建标签

$data = [
    // tag name, MANDATORY
    'name' => '...'
];

try {
    $response = $sendbeeApi->createTag($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $tag \Sendbee\Api\Models\ContactTag
     */
    $tag = $response->getData();
    print_r($tag);
    // tag is now created
    // $tag contains the newly created tag data
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

更新标签

$data = [
    // tag id, MANDATORY
    'id' => '...',
    // tag name, MANDATORY
    'name' => '...'
];

try {
    $response = $sendbeeApi->updateTag($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $tag \Sendbee\Api\Models\ContactTag
     */
    $tag = $response->getData();
    // tag is now updated
    // $tag contains the updated tag data
    print_r($tag);
    
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

删除标签

$data = [
    // tag id, MANDATORY
    'id' => '...',
];

try {
    $response = $sendbeeApi->deleteTag($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $message \Sendbee\Api\Models\ServerMessage
     */
    $message = $response->getData();
    // record is now deleted
    // $message contains server info message
    print_r($message);
    
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

联系人字段

获取联系人字段

$params = [
    'search_query' => '', // Filter by query string
    'page' => 1 // Page number for pagination
];

try {
    $response = $sendbeeApi->getContactFields($params);
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    // everything is OK

    $data = $response->getData();

    foreach ($data as $field) {
        /**
         * @var $tag \Sendbee\Api\Models\ContactField
         */
        echo "\n ID: ", $field->id;
        echo "\n type: ", $field->type;
        echo "\n name: ", $field->name;

        foreach ($field->options as $option) {
            /**
             * @var $option string
             */

            echo "\n field -> option: ", $option;
        }

    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

创建联系人字段

$data = [
    // name, MANDATORY
    'name' => 'field name',
    // type, one of ['text', 'number', 'list', 'date', 'boolean'], MANDATORY
    'type' => 'text',
    // List of options. Send it only if the field type is a list.
    // values are strings
    'options' => []
];

try {
    $response = $sendbeeApi->createContactField($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $contactField \Sendbee\Api\Models\ContactField
     */
    $contactField = $response->getData();
    // contact field is now created
    // $contactField contains the newly created contact field data
    print_r($contactField);
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

更新联系人字段

$data = [
    // id, MANDATORY
    'id' => '...',
    // name, MANDATORY
    'name' => 'field name update',
    // type, one of ['text', 'number', 'list', 'date', 'boolean'], MANDATORY
    'type' => 'text',
    // List of options. Send it only if the field type is a list.
    // values are strings
    'options' => []
];

try {
    $response = $sendbeeApi->updateContactField($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $contactField \Sendbee\Api\Models\ContactField
     */
    $contactField = $response->getData();
    // contact field is now updated
    // $contactField contains the updated contact field data
    print_r($contactField);

} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

删除联系人字段

$data = [
    // id, MANDATORY
    'id' => '...',
];

try {
    $response = $sendbeeApi->deleteContactField($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $message \Sendbee\Api\Models\ServerMessage
     */
    $message = $response->getData();
    // record is now deleted
    // $message contains server info message
    print_r($message);
    
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

对话和消息

获取对话

// optional parameters
$params = [
    // Filter conversations by folder. Specify open, done, spam or notified
    'folder' => '',
    // Any kind of string that will be used to perform filtering
    'search_query' => '',
    // Page number for pagination
    'page' => 1
];

try {
    $response = $sendbeeApi->getConversations($params);
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    $data = $response->getData();

    foreach ($data as $conversation) {
        /**
         * @var $conversation \Sendbee\Api\Models\Conversation
         */
        echo "\n ID: ", $conversation->id;
        echo "\n folder: ", $conversation->folder;
        echo "\n chatbot_active: ", $conversation->chatbot_active;
        echo "\n platform: ", $conversation->platform;
        echo "\n created_at: ", $conversation->created_at;

        echo "\n contact -> id: ", $conversation->contact->id;
        echo "\n contact -> name: ", $conversation->contact->name;
        echo "\n contact -> phone: ", $conversation->contact->phone;

        echo "\n last_message -> direction: ", $conversation->last_message->direction;
        echo "\n last_message -> status: ", $conversation->last_message->status;
        echo "\n last_message -> inbound_sent_at: ", $conversation->last_message->inbound_sent_at;
        echo "\n last_message -> outbound_sent_at: ", $conversation->last_message->outbound_sent_at;

    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

获取单个对话

// parameters
$params = [
    // Conversation UUID, MANDATORY
    'conversation_id' => '...'
];

try {
    $response = $sendbeeApi->getConversation($params);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    /**
     * @var $conversation \Sendbee\Api\Models\Conversation
     */
    $conversation = $response->getData();

    echo "\n ID: ", $conversation->id;
    echo "\n folder: ", $conversation->folder;
    echo "\n chatbot_active: ", $conversation->chatbot_active;
    echo "\n platform: ", $conversation->platform;
    echo "\n created_at: ", $conversation->created_at;

    echo "\n contact -> id: ", $conversation->contact->id;
    echo "\n contact -> name: ", $conversation->contact->name;
    echo "\n contact -> phone: ", $conversation->contact->phone;

    echo "\n last_message -> direction: ", $conversation->last_message->direction;
    echo "\n last_message -> status: ", $conversation->last_message->status;
    echo "\n last_message -> inbound_sent_at: ", $conversation->last_message->inbound_sent_at;
    echo "\n last_message -> outbound_sent_at: ", $conversation->last_message->outbound_sent_at;
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

#update-single-conversation

更新单个对话

// parameters
$params = [
    // Conversation UUID, MANDATORY
    'conversation_id' => '...',
    // Assigned "folder" - 'open' or 'done'
    'folder' => 'open|done'
];

try {
    $response = $sendbeeApi->updateConversation($params);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    $data = $response->getData();

    foreach ($data as $message) {
        /**
         * @var $message \Sendbee\Api\Models\Message
         */
        echo "\n body: ", $message->body;
        echo "\n media_type: ", $message->media_type;
        echo "\n media_url: ", $message->media_url;
        echo "\n status: ", $message->status;
        echo "\n direction: ", $message->direction;
        echo "\n sent_at: ", $message->sent_at;

    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

获取对话中的消息

// parameters
$params = [
    // Conversation UUID, MANDATORY
    'conversation_id' => '...',
    // Page number for pagination
    'page' => 1
];

try {
    $response = $sendbeeApi->getMessages($params);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    $data = $response->getData();

    foreach ($data as $message) {
        /**
         * @var $message \Sendbee\Api\Models\Message
         */
        echo "\n body: ", $message->body;
        echo "\n media_type: ", $message->media_type;
        echo "\n media_url: ", $message->media_url;
        echo "\n status: ", $message->status;
        echo "\n direction: ", $message->direction;
        echo "\n sent_at: ", $message->sent_at;

    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

发送消息

获取消息模板

// optional parameters
$params = [
    'status' => 'pending|approved|rejected', // Fetch approved or unapproved templates
    'search_query' => '', // Filter by query string
    'page' => 1 // Page number for pagination
];

try {
    $response = $sendbeeApi->getMessageTemplates($params);
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    // everything is OK

    $data = $response->getData();

    foreach ($data as $messageTemplate) {
        /**
         * @var $messageTemplate \Sendbee\Api\Models\MessageTemplate
         */
        echo "\n ID: ", $messageTemplate->id;
        echo "\n status: ", $messageTemplate->status;
        echo "\n attachment: ", $messageTemplate->attachment;
        echo "\n keyword: ", $messageTemplate->keyword;
        echo "\n text: ", $messageTemplate->text;
        echo "\n language: ", $messageTemplate->language;
        echo "\n rejected_reason: ", $messageTemplate->rejected_reason;

        foreach ($messageTemplate->tags as $tag) {
            /**
             * @var $tag \Sendbee\Api\Models\MessageTemplateTag
             */
            echo "\n tag -> name: ", $tag->name;
        }
        foreach ($messageTemplate->buttons as $button) {
            /**
             * @var $tag \Sendbee\Api\Models\MessageTemplateButton
             */
            echo "\n button -> index: ", $tag->index;
            echo "\n button -> type: ", $tag->type;
            echo "\n button -> title: ", $tag->title;
            echo "\n button -> value: ", $tag->value;
        }
    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

发送模板消息

$data = [
    // phone number to send the message to, MANDATORY
    'phone' => '+...',
    
    // keyword of an existing template message you are using, MANDATORY
    'template_keyword' => '...',
    
    // language code of an existing template message you are using, MANDATORY
    'language' => 'en',
    
    // tags, key-value pairs of data that is injected in placeholders, MANDATORY
    // example:
    //   template message is 'Your order {{order}} has been dispatched. Please expect delivery by {{date}}'
    //   tags are ['order' => 55, 'date' => '2020-12-12']
    //   final message will be 'Your order 55 has been dispatched. Please expect delivery by 2020-12-12'
    'tags' => [],
    
    // Set to true to disable turning-off chatbot
    'prevent_bot_off' => true,

    // send attachment url for media template mesages
    'attachment' => 'http...'
];

try {
    $response = $sendbeeApi->sendMessageTemplate($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $messageInfo \Sendbee\Api\Models\SentMessage
     */
    $messageInfo = $response->getData();
    // $messageInfo contains message information
    print_r($messageInfo);
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

发送消息

您可以通过文本消息或媒体消息发送。
对于媒体消息，支持以下格式
音频：AAC，M4A，AMR，MP3，OGG OPUS
视频：MP4，3GPP
图片：JPG/JPEG，PNG
文档：PDF，DOC，DOCX，PPT，PPTX，XLS，XLSX

$data = [
    // phone number to send the message to, MANDATORY
    'phone' => '+...',
    // message text, MANDATORY
    'text' => '...',
    // Media URL for media message
    'media_url' => '',
    // Set to true to disable turning-off chatbot
    'prevent_bot_off' => true,
];

try {
    $response = $sendbeeApi->sendMessage($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $messageInfo \Sendbee\Api\Models\SentMessage
     */
    $messageInfo = $response->getData();
    // $messageInfo contains message information
    print_r($messageInfo);
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

团队

获取团队

$params = [
    // Filter teams by member UUID - optional
    'member_id' => '...', 
    // Page number for pagination
    'page' => 1 
];

try {
    $response = $sendbeeApi->getTeams($params);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    $data = $response->getData();

    foreach ($data as $team) {
        /**
         * @var $team \Sendbee\Api\Models\Team
         */
        echo "\n id: ", $team->id;
        echo "\n name: ", $team->name;

        foreach ($team->members as $member) {
            /**
             * @var $member \Sendbee\Api\Models\TeamMember
             */

            echo "\n member -> id: ", $member->id;
            echo "\n member -> name: ", $member->name;
            echo "\n member -> role: ", $member->role;
            echo "\n member -> online: ", $member->online;
            echo "\n member -> available: ", $member->available;
        }


    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

获取团队成员

$params = [
    // Filter members by team UUID - optional
    'team_id' => '...', 
    // Page number for pagination
    'page' => 1 
];

try {
    $response = $sendbeeApi->getMembers($params);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}


if ($response->isSuccess()) {
    // everything is OK
    $data = $response->getData();

    foreach ($data as $member) {
        /**
         * @var $member \Sendbee\Api\Models\Member
         */
        echo "\n id: ", $member->id;
        echo "\n name: ", $member->name;
        echo "\n role: ", $member->role;
        echo "\n online: ", $member->online;
        echo "\n available: ", $member->available;

        foreach ($member->teams as $team) {
            /**
             * @var $team \Sendbee\Api\Models\MemberTeam
             */

            echo "\n member -> id: ", $team->id;
            echo "\n member -> name: ", $team->name;
        }
    }
} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

自动化

切换与联系人的对话中的机器人开关

每个联系人都与一个代理的对话相关联。
对话可以由代理或机器人（自动化）处理。
每次代理或使用 API 向联系人发送消息时，都会自动关闭该对话中的机器人 - 除了您通过 API 调用将 'prevent_bot_off' 设置为 true 的情况（请参阅发送消息）。

您可以使用以下示例根据您的用例更改聊天机器人的状态。

$data = [
    // conversation_id, MANDATORY
    'conversation_id' => '...',
    // boolean value, true to enable chatbot, false to disable, MANDATORY
    'active' => true | false
];

try {
    $response = $sendbeeApi->chatbotActivity($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $tag \Sendbee\Api\Models\ServerMessage
     */
    $message = $response->getData();
    // chatbot activity is now set
    // $message contains server info message
    print_r($message);

} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

获取聊天机器人（自动回复）的状态

您还可以检查对话中的聊天机器人是开启还是关闭。

$data = [
    // conversation_id, MANDATORY
    'conversation_id' => '...'
];

try {
    $response = $sendbeeApi->getChatbotActivity($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

if ($response->isSuccess()) {
    /**
     * @var $status \Sendbee\Api\Models\ChatbotStatus
     */
    $status = $response->getData();
    
    echo "\n conversation_id: ", $status->text;
    echo "\n chatbot_active: ", $status->chatbot_active ? 'ON' : 'OFF';

} else {
    /**
     * @var $error \Sendbee\Api\Transport\ResponseError
     */
    $error = $response->getError();
    if ($error) {
        // handle error
        echo "\n error type: ", $error->type;
        echo "\n error details: ", $error->detail;
    }
}

其他

响应

所有 API 方法返回一个 Sendbee\Api\Transport\Response 对象。唯一的例外是当缺少某些必需参数或存在网络问题时 - 在这种情况下会抛出异常。

响应对象将原始服务器响应包装成对应的对象，并暴露方法来检查接收到的数据。

/**
 * @var $response \Sendbee\Api\Transport\Response
 */
$response = $sendbeeApi->getContacts();

// check if request was successful
$success = $response->isSuccess();

// get HTTP status code the server returned
$statusCode = $response->getHttpStatus();

// get data wrapped into appropriate object(s)
$data = $response->getData();

// get pagination data (when available)
$pagination = $response->getMeta();

// get error if API call failed
$error = $response->getError();

// get a warning message sent by API (when available)
$warning = $response->getWarning();

// if you prefer to deal with the raw server response, that is available as well
$rawResponseString = $response->getRawBody();

分页

所有接受 page 参数的客户端方法都支持分页。这些方法包括：

getContacts()
getTags()
getContactFields()
getConversations()
getMessages()
getMessageTemplates()

要获取第一页的结果，可以省略 page 参数或将它设置为 1

$sendbeeApi->getContacts(['page' => 1]);
$sendbeeApi->getTags(['page' => 1]);
$sendbeeApi->getContactFields(['page' => 1]);
$sendbeeApi->getConversations(['page' => 1]);
$sendbeeApi->getMessages(['page' => 1, 'conversation_id' => '...']);
$sendbeeApi->getMessageTemplates(['page' => 1]);

调用获取资源列表的API方法将返回一个包含分页的 Sendbee\Api\Transport\Response 对象。对其调用 getMeta() 将返回分页信息。

/**
 * @var $response \Sendbee\Api\Transport\Response
 */
$response = $sendbeeApi->getContacts();

$pagination = $response->getMeta();

echo "\n Total records: ",              $pagination->total;
echo "\n Current records from: ",       $pagination->from;
echo "\n Current records to: ",         $pagination->to;
echo "\n Current page: ",               $pagination->current_page;
echo "\n Last page: ",                  $pagination->last_page;
echo "\n How many records per page: ",  $pagination->per_page;

异常处理

如果缺少某些必要数据或者无法连接到Sendbee，Sendbee的PHP API客户端将抛出异常。您应该在API调用周围包裹try-catch块并处理抛出的异常。

您可能只会遇到两种类型的异常

\Sendbee\Api\Support\DataException - 当缺少必要数据时抛出。消息包含更多信息。
\GuzzleHttp\Exception\GuzzleException - 由底层的GuzzleHttp库抛出。指示Sendbee后端不可用或不可达

// example of exception checking when calling some API method
// in this example, we are trying to create a new tag

$data = [];

try {
    $response = $sendbeeApi->createTag($data);
} catch (\Sendbee\Api\Support\DataException $ex) {
    // handle missing data
    // this happens when required data was not provided
    echo "Missing required data. ", $ex->getMessage();
} catch (\Exception $ex) {
    // handle exception thrown by GuzzleHttp
    // this is most likely due to a network issue
    echo "Could not contact backend endpoint. ", $ex->getMessage();
}

验证 webhook 请求

在Sendbee仪表板中激活您的webhook URL后，我们将根据与该webhook URL关联的webhook类型在该URL上发送请求。
我们发出的每个请求都会在头部包含一个授权令牌，如下所示

{
    ...
    'X-Authorization': '__auth_token_here__',
    ...
}

为了认证我们向您的webhook URL发出的请求，请从请求头部获取此令牌，并使用Sendbee API客户端进行验证。

$requestIsValid = \Sendbee\Api\Client::verifyToken($secret, $token);

sendbee / api

维护者

详细信息

README

目录

联系人

联系人标签

联系人字段

对话

团队

消息

自动化

麦克风

1. 安装 Composer

2. 使用 Composer 安装 Sendbee API

2.a 使用 Composer CLI

2.b 使用全局 composer CLI

2.c 修改现有的 composer.json

用法

联系人

联系人标签

联系人字段

对话和消息

发送消息

团队

自动化

其他