Download the PHP package sendbee/api without Composer

AI Number PHP API Client

Table of contents

• Installation
• Initialization

Contacts

• Fetch contacts
• Subscribe contact
• Update contact

Contact Tags

• Fetch tags
• Create tag
• Update tag
• Delete tag

Contact Fields

• Fetch contact fields
• Create contact field
• Update contact field
• Delete contact field

Conversations

• Fetch conversations
• Fetch single conversation
• Update single conversation
• Fetch messages

Teams

• Fetch teams
• Fetch team members

Messages

• Fetch message templates
• Send template message
• Send message

Automation

• Toggle bot for conversation with contact on off
• Get chatbot (automated responses) status

Mics

• Rate Limiting
• Pagination
• Exception handling
• Authenticate webhook request
• Official Documentation

Requirements

• PHP 5.5 or higher
• Guzzle HTTP client 6.5+ or 7.0+
• Composer

PHP 8.2+ Compatibility

This library is fully compatible with PHP 8.2 and later versions. The library supports both Guzzle 6.5+ and Guzzle 7.x to ensure compatibility across different PHP versions:

• PHP 7.x: Compatible with Guzzle 6.5+ and Guzzle 7.x
• PHP 8.0+: Recommended to use Guzzle 7.x for best performance and to avoid deprecation warnings
• PHP 8.2+: Requires Guzzle 7.x to avoid deprecation warnings

When installing on PHP 8.2+, Composer will automatically install Guzzle 7.x.

Enhanced Model Support

The client library includes comprehensive model support with all fields returned by the Sendbee API. Recent enhancements include:

Contact Model:

• modified_at - Timestamp when contact was last modified
• has_messaging_consent - Boolean indicating if contact has given messaging consent
• whatsapp_user_id - WhatsApp Business-scoped user ID (BSUID), example US.13491208655302741918

ConversationContact Model:

• whatsapp_user_id - WhatsApp Business-scoped user ID (BSUID) of the conversation contact

ContactTag Model:

• editable - Boolean indicating if tag can be edited
• disable_contact - Boolean indicating if tag disables contact
• icons - Array of icon data

ContactNote Model:

• id - UUID identifier for the note

Message Model:

• id - UUID identifier for the message
• fail_reason - Reason for message failure (when applicable)
• action - Action associated with the message
• meta_data - Additional metadata as an array
• from_user_id - UUID of sender user
• to_user_id - UUID of recipient user

MessageTemplate Model:

• rejected_reason - Reason for template rejection (when applicable)
• name - Template name
• category - Template category
• button_tags - Collection of tags for buttons

MessageTemplateButton Model:

• icon - Icon data as an array/object
• action - Button action type
• flow_action - Flow action identifier
• navigate_screen - Screen navigation target
• flow_id - Associated flow identifier
• url_type - Type of URL for the button

All models are automatically populated from API responses, ensuring type safety and easy access to all available data.

Installation

The recommended way to install Sendbee API is with Composer.

1. Install Composer

2. Install Sendbee API using Composer

2.a Using Composer CLI

You can add Sendbee API as a dependency using the composer.phar CLI:

2.b Using global composer CLI

If Composer is available globally on your system, you can run the following from your project root.

2.c Modifying existing composer.json

If you have an existing project that uses Composer and has composer.json file, you can specify sendbee/api as a dependency.

After adding a dependency you should tell composer to update dependencies

Usage

Autoload

After installing, you need to require Composer's autoloader:

You can find out more on how to install Composer, configure autoloading, and other best-practices for defining dependencies at Composer.

Initialization

To initialize the API client, you'll need a public key and secret. That data is available in your Sendbee dashboard.

Contacts

Fetch contacts

Subscribe contact

Update contact

Contact tags

Fetch tags

Create tag

Update tag

Delete tag

Contact fields

Fetch contact fields

Create contact field

Update contact field

Delete contact field

Conversations and messages

Fetch conversations

Fetch single conversation

update-single-conversation

Update a single conversation

Fetch messages in a conversation

Sending messages

Fetch message templates

Send template message

Send message

You can send either text message or media message.
For media message, following formats are supported:
Audio: AAC, M4A, AMR, MP3, OGG OPUS
video: MP4, 3GPP
Image: JPG/JPEG, PNG
Documents: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX

Teams

Fetch teams

Fetch team members

Automation

Toggle bot for conversation with contact on off

Every contact is linked with conversation with an agent.
Conversation could be handled by an agent or a bot (automation).
Every time a message has been sent to a contact by an agent or using the API, the bot is automatically turned off for that conversation - except when you set 'prevent_bot_off' to true via API call (see Send message).

Use the example below to change the chatbot status based on your use case.

Get chatbot (automated responses) status

You can also check if chatbot is turned on or off for a conversation.

Misc

Response

All API methods return a Sendbee\Api\Transport\Response object. Only exception is when some required parameter is missing or there are network issues - in that case an exception is thrown.

The response object wraps the raw server response into corresponding objects and exposes methods to inspect received data.

Rate Limiting

The Sendbee API enforces a rate limit of 60 requests per minute. When this limit is exceeded, the API returns a 429 Too Many Requests status code along with a Retry-After header indicating how many seconds to wait before retrying.

Automatic Rate Limit Handling

The PHP client library automatically handles rate limiting for you:

• When a 429 response is received, the client automatically retries the request up to 3 times
• The client reads the Retry-After header and waits the specified duration before retrying (defaults to 30 seconds if header is missing)
• Retry attempts are logged to help with debugging
• This behavior is transparent and requires no additional code from you

Monitoring Rate Limits

You can monitor your rate limit usage by inspecting response headers:

HTTP Timeouts

The client is configured with the following timeouts:

• Request timeout: 30 seconds (maximum time for the entire request to complete)
• Connection timeout: 10 seconds (maximum time to establish a connection)

These timeouts are designed to work well with the API's rate limiting and ensure reliable operation even during high-volume operations.

Pagination

Pagination is available on all client methods that accept a page parameter. Those methods are:

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

To get the first page of results you can omit the page parameter or set it to 1

Calling API methods that get a list of resources will return a Sendbee\Api\Transport\Response object containing pagination. Calling getMeta() on it will return pagination information.

Exception handling

Sendbee API client for PHP will throw an Exception is some required data is missing or it is unable to connect to Sendbee. You should wrap API calls in a try-catch block and handle thrown exceptions.

You should only encounter 2 types of exceptions:

• \Sendbee\Api\Support\DataException - Thrown when required data is missing. Message contains more information.

• \GuzzleHttp\Exception\GuzzleException - Thrown by underlying GuzzleHttp library. Indicates Sendbee backend is unavailable/unreachable

Authenticate webhook request

After activating your webhook URL in Sendbee Dashboard, we will start sending requests on that URL depending on which webhook type is linked with that webhook URL.
Every request that we make will have authorization token in header, like this:

To authenticate requests that we make to your webhook URL, take this token from request header and check it using Sendbee API Client: