BulkGate

https://help.bulkgate.com

BulkGate is an SMS gateway platform that enables users to send SMS campaigns, manage contacts,...

Tokens:79,922

Snippets:935

Trust Score:9.5

Update:3 months ago

Show doc for...

Tokens:

Tokens:

### Full request example

Source: https://help.bulkgate.com/docs/en/http-address-book-add.html

A complete example of a POST request including authentication and contact data.

```json
POST /api/1.0/address-book/add HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "groups": [1, 2],
    "group_name": "Talos 1",
    "data": {
         "first_name": "Morgan",
         "last_name": "Yu",
         "phone_mobile": "123456789",
         "street1": "Crew's quarters",
         "street2": "Executive suite",
         "country": "Talos 1",
         "email": "morganyu@talos.com"
    }
}
```

--------------------------------

### Full API Request Example

Source: https://help.bulkgate.com/docs/en/http-subscribe-groups.html

A complete example of the POST request body including application credentials.

```json
POST /api/1.0/subscribe/groups HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-one-time-password-resend.html

A complete example of the POST request body including authentication and the OTP ID.

```json
POST /api/1.0/otp/resend HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",
    "id": "opt-id"
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-black-list-add.html

A complete JSON payload example for adding numbers to the black list.

```json
POST /api/1.0/black-list/add HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",     
  "numbers": ["420123456789", "420987654321"],
  "wallet": "WALLET",
  "type": "black-list",
  "source_id": "api-my-import",
  "reason": "Because it's thursday"
}
```

--------------------------------

### Run Magento 2 setup commands

Source: https://help.bulkgate.com/docs/en/magesms-module-installation.html

Execute these commands from the Magento 2 root directory to upgrade the setup and deploy static content after uploading the module files.

```bash
php bin/magento setup:upgrade
```

```bash
php bin/magento setup:static-content:deploy
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-price-list-get.html

A complete example of a POST request body including authentication and country parameters.

```json
POST /api/1.0/price-list/get HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "country": ["sk", "cz"],
    "wallet": "#######################"
}
```

--------------------------------

### API Response Examples

Source: https://help.bulkgate.com/docs/en/http-low-level-api-send-bulk-sms-same-text.html

Examples of successful and error responses from the API.

```xml
<stat>1</stat><info>2556b1d0-5ced-11e3-8a4f-00000a0a0211</info>
```

```xml
<stat>3</stat><info>10</info>
```

```xml
<stat>1</stat><info>6b1d01231231231</info>QQQ___QQQ<stat>3</stat><info>9</info>
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-black-list-load.html

A complete example of a POST request including the JSON body with required and optional parameters.

```http
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",     
  "campaign_id": "id-bulkgate-000001",
  "wallet": "wallet_id",
  "from": "2018-05-14T18:30:00-01:00",
  "to": "2018-05-15T18:30:00-01:00"
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-subscribe-subscribers.html

A complete example of a POST request including the JSON body with authentication and group parameters.

```json
POST /api/1.0/subscribe/subscribers HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "group": 1
}
```

--------------------------------

### Full OTP Request Example

Source: https://help.bulkgate.com/docs/en/http-one-time-password-send.html

A complete JSON payload example demonstrating configuration for SMS, Viber, and RCS channels.

```json
POST /api/1.0/otp/send HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",
  "number": "44777777777",
  "country": "gb",
  "language": "en",
  "code_type": "string",
  "code_length": 7,
  "request_quota_number": 1,
  "request_quota_identification": "127.0.0.1",
  "trials_available_resend": 2,
  "trials_available_verification": 5,
  "daily_limit": 100,
  "daily_limit_country": ['cz' => 150, 'sk' => 50],
  "expiration": 3600,
  "channel": {
    "rcs": {
      "sender": "Lt. Hagan",
      "expiration": 100
    },
    "viber": {
      "sender": "Lt. Hagan",
      "expiration": 100
    },
    "sms": {
      "sender_id": "gText",
      "sender_id_value": "Lt-Hagan",
      "unicode": true
    }
  }
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-address-book-remove.html

A complete example of the JSON payload required to remove a contact.

```json
POST /api/1.0/address-book/remove HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "phone_number": "123456789",
}
```

--------------------------------

### Full API Request Example

Source: https://help.bulkgate.com/docs/en/http-shortener-change.html

A complete JSON payload example for modifying a shortened URL.

```http
POST /api/1.0/shortener/change HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",     
  "short_url": "u1.pm/K",
  "target_url": "www.insymbo.com"
}
```

--------------------------------

### API response examples

Source: https://help.bulkgate.com/docs/en/http-address-book-add.html

Examples of successful and error responses returned by the API.

```json
{
    "data": {
        "message": "contact_has_been_added",
        "groups": [1,2,3]
    }
}
```

```json
{
    "type": "contact_with_this_phone_number_already_exists",
    "code": 400,
    "error": "Contact with this phone number already exists",
    "detail": null
}
```

```json
{
    "type": "invalid_phone_mobile",
    "code": 400,
    "error": "Invalid phone mobile",
    "detail": null
}
```

```json
{
    "type": "group_not_found",
    "code": 400,
    "error": "Group not found",
    "detail": null
}
```

--------------------------------

### Use Fluent Interface

Source: https://help.bulkgate.com/docs/en/php-sdk-message-phone-number.html

Chain multiple configuration methods together for concise object setup.

```php
/** @var BulkGate\Sms\Message\PhoneNumber $phone_number */
$phone_number
    ->phoneNumber('7971700001')
    ->iso(BulkGate\Sms\Country::UNITED_KINGDOM);
```

--------------------------------

### Full Import Request Example

Source: https://help.bulkgate.com/docs/en/http-address-book-import.html

A complete JSON payload example for importing multiple contacts into specified groups.

```json
POST /api/1.0/address-book/import HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "groups": [1, 2],
    "group_name": "Talos 1",
    "data": [
    {
        "first_name": "Morgan",
        "last_name": "Yu",
        "phone_mobile": "789456123"
    },
    {
        "first_name": "Alex",
        "last_name": "Yu",
        "phone_mobile": "123456789"
    }
  ]
}
```

--------------------------------

### Full API Request Example

Source: https://help.bulkgate.com/docs/en/http-subscribe-send.html

A complete JSON payload example including application credentials, group ID, text, image, and button configuration.

```json
POST /api/1.0/subscribe/send HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "group": 1,
    "text": "Test",
  "image": "<url>",
  "button": {
    "text": "text",
    "url": "<url>"
  }
}
```

--------------------------------

### Full Unsubscribe Request Example

Source: https://help.bulkgate.com/docs/en/http-subscribe-unsubscribe.html

A complete example of the JSON payload required to unsubscribe users from a group.

```json
POST /api/1.0/subscribe/unsubscribe HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "group": 1,
  "identification": ["telegram:########", "line:################"]
}
```

--------------------------------

### Template object request example

Source: https://help.bulkgate.com/docs/en/http-advanced-whatsapp.html

Example of a complete JSON request payload using a WhatsApp template with header, body, and button configurations.

```json
{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",
  "number": [
    "+420777777777"
  ],
  "text": "Test text",
  "channel": {
    "whatsapp": {
      "sender": "420777777777",
      "expiration": 300,
      "template": {
        "template": "test_template",
        "language": "cz",
        "header": {
          "type": "image",
          "url": "test_url",
          "caption": "test_caption"
        },
        "body": [
          {
            "type": "currency",
            "amount": 20.5,
            "currency": "euro"
          }
        ],
        "buttons": [
          {
            "type": "payload",
            "index": 1,
            "payload": "test_payload"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### GET /api/1.0/simple/promotional

Source: https://help.bulkgate.com/docs/en/http-simple-promotional-get.html

Sends a promotional SMS message using a GET request with query parameters.

```APIDOC
## GET /api/1.0/simple/promotional

### Description
Sends a promotional SMS message to one or more recipients using query parameters.

### Method
GET

### Endpoint
https://portal.bulkgate.com/api/1.0/simple/promotional

### Parameters
#### Query Parameters
- **application_id** (string) - Required - Your application ID.
- **application_token** (string) - Required - Your application token.
- **number** (string) - Required - Semicolon-separated list of phone numbers.
- **text** (string) - Required - The content of the SMS message.
- **unicode** (string) - Optional - Set to 'yes' to enable unicode support.
- **sender_id** (string) - Optional - Type of sender ID.
- **sender_id_value** (string) - Optional - Value of the sender ID.
- **country** (string) - Optional - ISO country code.
- **schedule** (string) - Optional - Scheduling time in ISO 8601 format or unix timestamp.
```

--------------------------------

### HTTP POST Request Example

Source: https://help.bulkgate.com/docs/en/http-api-bulk-delivery-confirmations-and-incoming-sms.html

Example of the JSON payload sent by the BulkGate server to your configured webhook URL.

```http
POST example.php HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

[
   {
      "status":"1",
      "smsID":"3t2563af3ff285",
      "price":"0.71",
      "date":"1904111007;1904111011"
   },
   {
      "status":"2",
      "smsID":"2t2563af3ff285",
      "price":"0.71",
      "date":"1904111007;1904111011"
   },
   {
      "status":"10",
      "from":"420777777777",
      "text":"answer text",
   }
]
```

--------------------------------

### Install BulkGate PHP SDK via Composer

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-v2.html

Use this command to add the SDK to your project dependencies.

```bash
composer require bulkgate/php-sdk
```

--------------------------------

### GET Request for Simple Info

Source: https://help.bulkgate.com/docs/en/http-simple-info-get-post.html

Use this URL structure to perform a GET request with application credentials as query parameters.

```http
https://portal.bulkgate.com/api/1.0/simple/info?application_id=<APPLICATION_ID>&application_token=<APPLICATION_TOKEN>
```

--------------------------------

### Initializing SMS Configurator

Source: https://help.bulkgate.com/docs/en/php-sdk-configurators-v2.html

Basic setup for an SMS message and its associated configurator.

```php
$message = new Sms('420777777777', 'text_message');
$sms_configurator = new SmsConfigurator();
```

--------------------------------

### File object request example

Source: https://help.bulkgate.com/docs/en/http-advanced-whatsapp.html

Example of a JSON request payload for sending a file attachment via WhatsApp.

```json
{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",
  "number": [
    "+420777777777"
  ],
  "text": "Test text",
  "channel": {
    "whatsapp": {
      "sender": "420777777777",
      "expiration": 300,
      "file": {
        "type": "image",
        "url": "url_test",
        "caption": "caption_test"
      }
    }
  }
}
```

--------------------------------

### Credit Balance Request Example

Source: https://help.bulkgate.com/docs/en/http-advanced-check-credit-balance.html

A sample JSON request body containing the required application credentials.

```json
POST /api/2.0/advanced/info HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "<APPLICATION_ID>", 
    "application_token": "<APPLICATION_TOKEN>"
}
```

--------------------------------

### Install SDK via Composer

Source: https://help.bulkgate.com/docs/en/php-sdk-installation.html

Use this command in your terminal to add the package to your project dependencies.

```bash
composer require bulkgate/sms
```

--------------------------------

### Inject SDK into a Service

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-nette-v2.html

Example of using the injected BulkGate Sender in a custom class.

```php
use BulkGate\Sdk\Sender;
use BulkGate\Sdk\Message\Sms;

class Sdk
{
    private Sender $sender;

    public funnction __construct(Sender $sender)
    {
        $this->sender = $sender;
    }
    

    public function sendMessage(string $phone_number, string $text): void
    {    
        $this->sender->send(new Sms($phone_number, $text));
    }
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-address-book-edit.html

A complete JSON payload for editing a contact's information.

```json
POST /api/1.0/address-book/edit HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "phone_number": "123456789",
    "data": {
        "first_name": "Morgan",
        "last_name": "Yu",
        "phone_mobile": "123456789",
        "street1": "Crew's quarters",
        "street2": "Executive suite",
        "country": "Talos 1",
        "email": "morganyu@talos.com"
    }
}
```

--------------------------------

### GET /api/1.0/simple/info

Source: https://help.bulkgate.com/docs/en/http-simple-info-get-post.html

Retrieves account information using query parameters.

```APIDOC
## GET /api/1.0/simple/info

### Description
Retrieves account information using application credentials passed as query parameters.

### Method
GET

### Endpoint
https://portal.bulkgate.com/api/1.0/simple/info

### Parameters
#### Query Parameters
- **application_id** (string) - Required - Your application ID.
- **application_token** (string) - Required - Your application token.
```

--------------------------------

### Message object request example

Source: https://help.bulkgate.com/docs/en/http-advanced-whatsapp.html

Example of a JSON request payload for sending a standard text message via WhatsApp.

```json
{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",
  "number": [
    "+420777777777"
  ],
  "text": "Test text",
  "channel": {
    "whatsapp": {
      "sender": "420777777777",
      "expiration": 300,
      "message": {
        "text": "title",
        "preview_url": true
      }
    }
  }
}
```

--------------------------------

### Full Request Example

Source: https://help.bulkgate.com/docs/en/http-address-book-get.html

Complete POST request including headers and JSON body with authentication and phone number.

```http
POST /api/1.0/address-book/get HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "##################################################",
    "phone_number": "123456789",
}
```

--------------------------------

### Full Verification Request

Source: https://help.bulkgate.com/docs/en/http-one-time-password-verify.html

Example of a complete JSON payload for verifying an OTP.

```json
POST /api/1.0/otp/verify HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",
    "id": "otp-id",
    "code": "0000"
}
```

--------------------------------

### Example Response for Message

Source: https://help.bulkgate.com/docs/en/php-sdk-sender.html

The structure of a response object after sending a single message.

```text
BulkGate\Message\Response Object
(
    [data:BulkGate\Message\Response:private] => Array
    (
        [sms_id] => tmpde8f0dca011
        [price] => 0.033
        [credit] => 215.8138
        [number] => 447971700001
    )
)
```

--------------------------------

### Error Response Example

Source: https://help.bulkgate.com/docs/en/http-advanced-check-credit-balance.html

The JSON structure returned when authentication or other errors occur.

```json
{
  "error": "authentication_failed",
  "code": 401
}
```

--------------------------------

### Example Response for BulkMessage

Source: https://help.bulkgate.com/docs/en/php-sdk-sender.html

The structure of a response object after sending a bulk message.

```text
BulkGate\Message\Response Object
(
    [data:BulkGate\Message\Response:private] => Array
    (
        [total] => Array
        (
            [price] => 0.033
            [status] => Array
            (
                [sent] => 0
                [accepted] => 1
                [scheduled] => 0
                [error] => 0
            )
        )
        [response] => Array
        (
            [0] => Array
            (
                [status] => accepted
                [sms_id] => tmpde8f0b47b12
                [price] => 0.033
                [credit] => 215.8138
                [number] => 447971700001
            )
        )
    )
)
```

--------------------------------

### Success Response Example

Source: https://help.bulkgate.com/docs/en/http-price-list-get.html

The JSON structure returned upon a successful request, containing operator pricing details.

```json
{
  "data": {
    "price_list": {
      "sk": [
        {
          "operator": "4ka",
          "operator_code": "23103",
          "type": "gSystem",
          "price": 0.03,
          "currency": "EUR",
          "gate": 0,
          "economy": false,
          "unicode": true,
          "two_way": true,
          "registration": false,
          "registration_fee": 0,
          "registration_delay": 0,
          "monthly_fee": 0,
          "route_quality": "HQ",
          "route_note": null,
          "sender_note": null,
          "default_senders": [
            "+##############"
          ]
        },
        {
          "operator": "O2",
          "operator_code": "23106",
          "type": "gSystem",
          "price": 0.03,
          "currency": "EUR",
          "gate": 0,
          "economy": false,
          "unicode": true,
          "two_way": true,
          "registration": false,
          "registration_fee": 0,
          "registration_delay": 0,
          "monthly_fee": 0,
          "route_quality": "HQ",
          "route_note": null,
          "sender_note": null,
          "default_senders": [
            "+###############"
          ]
        }
      ]
    }
  }
}
```

--------------------------------

### Success Response Example

Source: https://help.bulkgate.com/docs/en/http-advanced-check-credit-balance.html

The JSON structure returned upon a successful request, containing wallet and credit details.

```json
{
    "data": {
        "wallet": "bg1805151838000001",
        "credit": 215.8138,
        "currency": "credits",
        "free_messages": 51,
        "datetime": "2018-06-13T09:57:21+02:00"
    }
}
```

--------------------------------

### API Response Examples

Source: https://help.bulkgate.com/docs/en/http-address-book-import.html

JSON structures returned by the API for successful imports and error scenarios.

```json
{
    "data": {
        "message": "contacts_have_been_imported",
        "imported": 3,
        "groups": [1,2,3]
    }
}
```

```json
{
    "type": "no_valid_contacts_found",
    "code": 400,
    "error": "No valid contacts found",
    "detail": null
}
```

--------------------------------

### Install BulkGate SMS module via Composer

Source: https://help.bulkgate.com/docs/en/drupal-sms-installation.html

Use this command to download the module and its dependencies into your Drupal project.

```bash
composer require 'drupal/bulkgate_sms'
```

--------------------------------

### Retrieve ISO Code

Source: https://help.bulkgate.com/docs/en/php-sdk-message-phone-number.html

Get the currently assigned ISO code, which may return null if not set.

```php
/** @var BulkGate\Sms\Message\PhoneNumber $phone_number */
$phone_number->getIso(); // returns a string or null
```

--------------------------------

### Success Response Example

Source: https://help.bulkgate.com/docs/en/http-subscribe-subscribers.html

The JSON structure returned upon a successful API call, containing subscriber details.

```json
{
    "data": {
        "subscribers": [
            {
                "first_name": "#####",
                "last_name": "######",
                "first_name_vokativ": "#####x",
                "last_name_vokativ": "######",
                "identification": "telegram:########",
                "note": ""
            }
        ]
    }
}
```

--------------------------------

### Initialize Connection and Sender

Source: https://help.bulkgate.com/docs/en/php-sdk-installation.html

Create a connection instance using your application credentials and pass it to the sender.

```php
$connection = new BulkGate\Message\Connection('APPLICATION_ID', 'APPLICATION_TOKEN');

$sender = new BulkGate\Sms\Sender($connection);
```

--------------------------------

### GET /api/1.0/simple/transactional

Source: https://help.bulkgate.com/docs/en/http-simple-transactional-get.html

Sends a transactional SMS notification using a GET request.

```APIDOC
## GET /api/1.0/simple/transactional

### Description
Sends a transactional SMS notification. This endpoint is strictly for notification purposes.

### Method
GET

### Endpoint
https://portal.bulkgate.com/api/1.0/simple/transactional

### Query Parameters
- **application_id** (string) - Required - Your application ID.
- **application_token** (string) - Required - Your application token.
- **number** (string) - Required - The recipient phone number.
- **text** (string) - Required - The content of the SMS.
- **unicode** (string) - Optional - Set to 'yes' for unicode support.
- **sender_id** (string) - Optional - The type of sender ID.
- **sender_id_value** (string) - Optional - The value of the sender ID.
- **country** (string) - Optional - The country code (e.g., gb).

### Request Example
https://portal.bulkgate.com/api/1.0/simple/transactional?application_id=<APPLICATION_ID>&application_token=<APPLICATION_TOKEN>&number=447700900000&text=test_sms&unicode=yes&sender_id=gText&sender_id_value=BulkGate&country=gb
```

--------------------------------

### Manual SDK Creation

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-nette-v2.html

Instantiate the SDK manually if you are not using the DI container.

```php
use BulkGate\Sdk\Connection\ConnectionStream;
use BulkGate\Sdk\MessageSender;
use BulkGate\Sdk\Message\Sms;

$connection = new ConnectionStream(
    /*application_id: */ 0000, 
    /*application_token:*/ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
);

$sender = new MessageSender($connection);

$sender->send(new Sms($phone_number, $text));

/* Optional */

$sender->setTag('sdk');

$sender->setDefaultCountry('cz');

$viber_configurator = new ViberConfigurator('Sender');
$viber_configurator->button('Button Caption', 'https://www.bulkgate.com/');
$viber_configurator->image('https://www.example.com/example.png', true);
$viber_configurator->expiration(3_600);

$sender->addSenderConfigurator($viber_configurator);

$sms_configurator = new SmsConfigurator('gText', 'Example', true);

$sender->addSenderConfigurator($sms_configurator);

$sender->send(new Sms($phone_number, $text));
```

--------------------------------

### Initialize Connection and Sender

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-v2.html

Create a connection instance using your application ID and token, then instantiate the message sender.

```php
$connection = new ConnectionStream(/*application_id: */ 0000, /*application_token:*/ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
$sender = new MessageSender($connection);
```

--------------------------------

### Initialize PhoneNumber Instance

Source: https://help.bulkgate.com/docs/en/php-sdk-message-phone-number.html

Create a new instance by providing the phone number and an optional ISO country code.

```php
$phone_number = new PhoneNumber(
    "420777777777", 
    BulkGate\Sms\Country::UNITED_KINGDOM
);
```

--------------------------------

### Import SDK Classes

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-v2.html

Import the necessary namespaces for connection, messaging, and configuration.

```php
use BulkGate\Sdk\Connection\ConnectionStream;
use BulkGate\Sdk\MessageSender;
use BulkGate\Sdk\Scheduler\Simple;
use BulkGate\Sdk\Configurator\ViberConfigurator;
```

--------------------------------

### Initialize Sender Service

Source: https://help.bulkgate.com/docs/en/php-sdk-sender.html

Create a new instance of the Sender service using an existing connection.

```php
/** @var BulkGate\Message\Connection $connection */
$sender = new BulkGate\Sms\Sender($connection);
```

--------------------------------

### Import SenderSettings Namespace

Source: https://help.bulkgate.com/docs/en/php-sdk-sender-settings.html

Include the necessary namespace for sender settings configuration.

```php
use BulkGate\Sms\SenderSettings;
```

--------------------------------

### Validation Response Example

Source: https://help.bulkgate.com/docs/en/php-sdk-sender.html

The structure of a response object returned by the validation method.

```text
BulkGate\Message\Response Object
(
    [data:BulkGate\Message\Response:private] => Array
    (
        [447971700001] => Array
        (
            [number] => 447971700001
            [iso] => gb
            [prefix] => 44
            [area] => 44
            [length] => 12
            [area_found] => true
        )
        [77777777] => Array
        (
            [number] => 42077777777 
            [iso] => cz
            [prefix] => 420
            [area] => 420
            [length] => 8
            [area_found] => false
        )
    )
)
```

--------------------------------

### Advanced Promotional API Request Structure

Source: https://help.bulkgate.com/docs/en/http-advanced-promotional-v2.html

Full JSON payload example demonstrating multi-channel configuration including WhatsApp, RCS, Viber, and SMS settings.

```json
{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": [
        {"number": "420777777777", "text": "test1 <a>", "variables": {"a": 5}},
        {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}},
        {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
    ],
    "groups": [1, 2],
    "admins": [1, 4],
    "text": "RCS: The future of mobile messaging for businesses",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00",
    "channel": {
        "whatsapp": {
            "sender": "420777777777",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "rcs": {
            "sender": "BulkGate",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "viber": {
            "sender": "Lt. Hagan",
            "expiration": 100,
            "button": {
                "caption": "Go To BulkGate",
                "url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/"
            },
            "image": "https://www.bulkgate.com/wp-content/uploads/2023/06/rcs-rich-communication-services.jpg",
            "text": "*RCS: The future of mobile messaging for businesses*\n\nEver found yourself wishing you could send more than just text in an SMS, like a high-resolution image or an interactive button? Or perhaps you wished for a read receipt just to confirm your message got through? Rich Communication Services (RCS) is here to revolutionize the way businesses communicate, enhancing your messaging experience and overcoming these limitations."
        },
        "sms": {
            "sender_id": "gText",
            "sender_id_value": "Lt-Hagan",
            "unicode": true,
            "text": "RCS: The future of mobile messaging for businesses"
        }
    }
}
```

--------------------------------

### Import BulkMessage Class

Source: https://help.bulkgate.com/docs/en/php-sdk-bulk-message.html

Include the necessary class for creating bulk SMS campaigns.

```php
use BulkGate\Sms\BulkMessage;
```

--------------------------------

### Converting to String

Source: https://help.bulkgate.com/docs/en/php-sdk-message.html

Cast the message object to a string to get a formatted representation.

```php
/** @var BulkGate\Sms\Message $message */
$message = (string) $message; // into the variable
echo $message; // to the output
```

```text
447971700001: test message
```

--------------------------------

### API Endpoint URL

Source: https://help.bulkgate.com/docs/en/http-address-book-get.html

The base URL for the address book get request.

```text
https://portal.bulkgate.com/api/1.0/address-book/get
```

--------------------------------

### Define SMS Recipient

Source: https://help.bulkgate.com/docs/en/php-sdk-message-v2.html

Examples of defining the recipient using a string or a PhoneNumber object.

```php
$message = new Sms('420777777777', 'test message');
```

```php
$message = new Sms(new PhoneNumber('777777777', 'cz'), 'test message');
```

```php
$phone_number = new PhoneNumber();
$phone_number->phoneNumber('777777777');
$phone_number->iso('cz');
```

--------------------------------

### Initializing a message with variables

Source: https://help.bulkgate.com/docs/en/php-sdk-message-text.html

Create a new Text object by providing a template string and an associative array of variables for replacement.

```php
$text = 'Hi <name>, we wish you all the best to your <age> birthday!';

$variables = [
    'name' => 'John',
    'age' => '29'
];

$message_text = new Text($text, $variables);
```

--------------------------------

### API Response Structures

Source: https://help.bulkgate.com/docs/en/http-advanced-transactional-v2.html

Examples of successful message scheduling and common error responses.

```json
{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 2,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0,
                "duplicity_message": 0
            }
        },
        "response": [
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-0",
                "part_id": [
                    "transactional-64afe5f28ffc2-0"
                ],
                "number": "420777777777",
                "channel": "viber"
            },
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-1",
                "part_id": [
                    "transactional-64afe5f28ffc2-1"
                ],
                "number": "420777777778",
                "channel": "viber"
            }
        ]
    }
}
```

```json
{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Invalid phone number",
    "detail": null
}
```

```json
{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}
```

--------------------------------

### Importing Bulk Message Classes

Source: https://help.bulkgate.com/docs/en/php-sdk-bulk-message-v2.html

Required namespaces for initializing bulk message components.

```php
use BulkGate\Sdk\Message\{Sms, Viber, MultiChannel, Bulk};
use BulkGate\Sdk\Message\Component\{SimpleText, Button}
```

--------------------------------

### Convert to String

Source: https://help.bulkgate.com/docs/en/php-sdk-bulk-message.html

Cast the BulkMessage object to a string to get a formatted representation of the messages.

```php
/** @var BulkGate\Sms\BulkMessage $bulk_message */
$message = (string) $bulk_message; // into the variable
echo $bulk_message; // to the output
```

```text
447971700001: test1
447971700002: test2
447971700003: test3
447971700004: test4
797170000ř: test5
```

--------------------------------

### Defining Viber Message Recipients

Source: https://help.bulkgate.com/docs/en/php-sdk-message-viber-v2.html

Examples of setting the recipient using a string or a PhoneNumber object.

```php
$message = new Viber('420777777777', 'test message');
```

```php
$message = new Viber(new PhoneNumber('777777777', 'cz'), 'test message');
```

```php
$phone_number = new PhoneNumber();
$phone_number->phoneNumber('777777777');
$phone_number->iso('cz');
```

--------------------------------

### Import Sender Namespace

Source: https://help.bulkgate.com/docs/en/php-sdk-sender.html

Include the necessary namespace for the Sender service.

```php
use BulkGate\Sms\Sender;
```

--------------------------------

### Example of a personalized message

Source: https://help.bulkgate.com/docs/en/http-advanced-promotional-groups.html

This shows how variables in the message text are replaced with actual contact data.

```text
Hi Thomas, it is nice to meet you. lukas@example.com
```

--------------------------------

### Configure Nette DI Extension

Source: https://help.bulkgate.com/docs/en/php-sdk-installation-nette-v2.html

Register the BulkGate extension in your neon configuration file to inject the SDK into your services.

```neon
extensions:
    sdk: BulkGate\Sdk\DI\Extension

sdk:
    application_id: 0000
    application_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    sender:
        tag: 'sdk' # Optional
        default_country: cz # Optional
    configurator:
        sms: # Optional
            sender_id: gText
            sender_id_value: 'Example'
            unicode: true
        viber: # Optional
            sender: Sender
            button:
                caption: 'Button Caption'
                url: 'https://www.bulkgate.com/'
            image: 
                url: 'https://www.example.com/example.png'
                zoom: true
            expiration: 3600 # seconds
```

--------------------------------

### Successful API Response

Source: https://help.bulkgate.com/docs/en/http-simple-promotional.html

Example of a successful JSON response indicating the status of sent or scheduled messages.

```json
{
  "data": {
    "total": {
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "idfkvqrp-0",
        "part_id": [
                    "idfkvqrp-0_1",
                    "idfkvqrp-0_2",
                    "idfkvqrp-0"
                ],
        "number": "447700900000"
      },
      {
        "status": "scheduled",
        "sms_id": "idfkvqrp-1",
        "part_id": [
                    "idfkvqrp-1_1",
                    "idfkvqrp-1_2",
                    "idfkvqrp-1"
                ],
        "number": "447811901234"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "44771447678"
      }
    ]
  }
}
```

--------------------------------

### RCS Carousel Object Request

Source: https://help.bulkgate.com/docs/en/http-advanced-rcs.html

Example JSON payload for sending a carousel containing multiple cards.

```json
{
  "application_id": "APPLICATION_ID",
  "application_token": "APPLICATION_TOKEN",
  "number": [
    "+420777777777"
  ],
  "text": "Test text",
  "channel": {
    "rcs": {
      "sender": "BulkGate",
      "carousel": {
        "width": "medium",
        "cards": [
          {
            "title": "First",
            "description": "First card",
            "media": {
              "url": "PATH_TO_AN_IMAGE"
            },
            "suggestions": [
              ...
            ]
          },
          {
            "title": "Second",
            "description": "Second card",
            "media": {
              "url": "PATH_TO_AN_IMAGE"
            },
            "suggestions": [
              ...
            ]
          }
        ]
      }
    }
  }
}
```