Propagační SMS – příklady (Advanced API)
Příklady použití Advanced promotional, verze API 2.0. Alternativní kanály a kaskádu řeší Kaskáda kanálů.
Více příjemců
number přijímá pole telefonních čísel; všem odejde stejný text.
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420777777777",
"420777777778"
],
"text": "Spring sale starts today, up to 50 % off."
}
Vlastní text pro každého příjemce
Místo holého čísla můžete předat objekt s text, variables a country.
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
{
"number": "420777777777",
"text": "Hello John, spring sale starts today."
},
{
"number": "777777778",
"country": "sk",
"variables": {
"first_name": "Jana"
}
}
],
"text": "Hello <first_name>, spring sale starts today."
}
Čísla, skupiny i administrátoři najednou
Tyto tři zdroje se nevylučují - příjemci se sčítají. Viz Promotional groups a Promotional admins.
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420777777777"
],
"groups": [
974
],
"admins": [
154
],
"text": "Hello <first_name>, spring sale starts today."
}
Naplánovaná kampaň s ochranou proti duplicitám
same_number zahodí každou další zprávu na číslo, které už v kampani je; same_text zahodí jen zprávy se shodným textem.
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974
],
"text": "Spring sale starts today.",
"country": "cz",
"schedule": "2026-09-14T09:00:00+02:00",
"duplicates_check": "same_number",
"tag": "spring-sale"
}
Kampaň přes alternativní kanál
Viber s obrázkem a tlačítkem, SMS jako záchrana. Objekty kanálů popisují Kanály.
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974
],
"text": "Spring sale starts today, up to 50 % off.",
"channel": {
"viber": {
"sender": "BulkGate",
"image": "https://example.com/spring-sale.jpg",
"button": {
"caption": "Open the offer",
"url": "https://example.com/spring-sale"
}
},
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}
Odpověď je popsaná ve specifikaci.
Ukázky kódu
Níže je tentýž request v různých programovacích jazycích:
Význam jednotlivých parametrů popisuje specifikace.
PHP
php.net
$context = stream_context_create(['http' => [
'method' => 'POST',
'header' => 'Content-Type: application/json',
'content' => json_encode([
'application_id' => 451,
'application_token' => 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj',
'groups' => [974, 975],
'text' => 'Hello <first_name>, spring sale starts today.',
'duplicates_check' => 'same_number',
'channel' => [
'sms' => [
'sender_id' => 'gText',
'sender_id_value' => 'BulkGate',
],
],
], JSON_THROW_ON_ERROR),
'timeout' => 30,
'ignore_errors' => true,
]]);
$body = file_get_contents('https://portal.bulkgate.com/api/2.0/advanced/promotional', false, $context);
if ($body === false)
{
throw new RuntimeException('BulkGate API did not respond.');
}
$response = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
if (isset($response['error']))
{
throw new RuntimeException("BulkGate: {$response['error']} ({$response['type']})");
}
print_r($response['data']);
PHP cURL
php.net/curl
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://portal.bulkgate.com/api/2.0/advanced/promotional',
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'application_id' => 451,
'application_token' => 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj',
'groups' => [974, 975],
'text' => 'Hello <first_name>, spring sale starts today.',
'duplicates_check' => 'same_number',
'channel' => [
'sms' => [
'sender_id' => 'gText',
'sender_id_value' => 'BulkGate',
],
],
], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($curl);
$error = curl_error($curl);
curl_close($curl);
if ($error !== '')
{
throw new RuntimeException("BulkGate API: $error");
}
print_r(json_decode($body, true, flags: JSON_THROW_ON_ERROR));
PHP Guzzle
docs.guzzlephp.org
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
$client = new Client(['timeout' => 30, 'http_errors' => false]);
try
{
$result = $client->post('https://portal.bulkgate.com/api/2.0/advanced/promotional', ['json' => [
'application_id' => 451,
'application_token' => 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj',
'groups' => [974, 975],
'text' => 'Hello <first_name>, spring sale starts today.',
'duplicates_check' => 'same_number',
'channel' => [
'sms' => [
'sender_id' => 'gText',
'sender_id_value' => 'BulkGate',
],
],
]]);
}
catch (GuzzleException $e)
{
throw new RuntimeException('BulkGate: ' . $e->getMessage(), previous: $e);
}
$response = json_decode((string) $result->getBody(), true, flags: JSON_THROW_ON_ERROR);
print_r($response);
Go
go.dev
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://portal.bulkgate.com/api/2.0/advanced/promotional"
payload := strings.NewReader(`{"application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "groups": [974, 975], "text": "Hello <first_name>, spring sale starts today.", "duplicates_check": "same_number", "channel": {"sms": {"sender_id": "gText", "sender_id_value": "BulkGate"}}}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(body))
}
Python
python.org
import http.client, json
connection = http.client.HTTPSConnection('portal.bulkgate.com')
connection.request('POST', '/api/2.0/advanced/promotional', json.dumps({
'application_id': 451,
'application_token': 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj',
'groups': [974, 975],
'text': 'Hello <first_name>, spring sale starts today.',
'duplicates_check': 'same_number',
'channel': {
'sms': {
'sender_id': 'gText',
'sender_id_value': 'BulkGate',
},
},
}), {
'Content-Type': 'application/json'
})
response = connection.getresponse()
print(response.status, response.read().decode())
Node.js
nodejs.org
const response = await fetch("https://portal.bulkgate.com/api/2.0/advanced/promotional", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [974, 975],
"text": "Hello <first_name>, spring sale starts today.",
"duplicates_check": "same_number",
"channel": {
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}),
});
const result = await response.json();
if (result.error) {
throw new Error(`BulkGate: ${result.error} (${result.type})`);
}
console.log(result.data);
Java
java.net.http.HttpClient
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://portal.bulkgate.com/api/2.0/advanced/promotional"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974,
975
],
"text": "Hello <first_name>, spring sale starts today.",
"duplicates_check": "same_number",
"channel": {
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}"""))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
Kotlin
kotlinlang.org
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
val payload = """
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974,
975
],
"text": "Hello <first_name>, spring sale starts today.",
"duplicates_check": "same_number",
"channel": {
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}
""".trimIndent()
val request = HttpRequest.newBuilder()
.uri(URI.create("https://portal.bulkgate.com/api/2.0/advanced/promotional"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build()
val response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString())
println("${response.statusCode()} ${response.body()}")
C# .NET
learn.microsoft.com
using System.Net.Http;
using System.Text;
var payload = """
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974,
975
],
"text": "Hello <first_name>, spring sale starts today.",
"duplicates_check": "same_number",
"channel": {
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}
""";
using var client = new HttpClient();
var response = await client.PostAsync(
"https://portal.bulkgate.com/api/2.0/advanced/promotional",
new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine($"{(int) response.StatusCode} {await response.Content.ReadAsStringAsync()}");
C++ libcurl
curl.se/libcurl
#include <curl/curl.h>
#include <iostream>
#include <string>
static size_t collect(char *data, size_t size, size_t nmemb, std::string *out)
{
out->append(data, size * nmemb);
return size * nmemb;
}
int main()
{
const std::string payload = R"json(
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"groups": [
974,
975
],
"text": "Hello <first_name>, spring sale starts today.",
"duplicates_check": "same_number",
"channel": {
"sms": {
"sender_id": "gText",
"sender_id_value": "BulkGate"
}
}
}
)json";
CURL *curl = curl_easy_init();
if (curl == nullptr)
{
std::cerr << "curl_easy_init failed\n";
return 1;
}
curl_slist *headers = curl_slist_append(nullptr, "Content-Type: application/json");
std::string body;
curl_easy_setopt(curl, CURLOPT_URL, "https://portal.bulkgate.com/api/2.0/advanced/promotional");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload.c_str());
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, collect);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &body);
const CURLcode result = curl_easy_perform(curl);
long status = 0;
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &status);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
if (result != CURLE_OK)
{
std::cerr << curl_easy_strerror(result) << "\n";
return 1;
}
std::cout << status << " " << body << "\n";
return 0;
}
Ruby
ruby-lang.org
require 'json'
require 'net/http'
uri = URI('https://portal.bulkgate.com/api/2.0/advanced/promotional')
response = Net::HTTP.post(uri, {
'application_id' => 451,
'application_token' => 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj',
'groups' => [974, 975],
'text' => 'Hello <first_name>, spring sale starts today.',
'duplicates_check' => 'same_number',
'channel' => {
'sms' => {
'sender_id' => 'gText',
'sender_id_value' => 'BulkGate'
}
}
}.to_json, 'Content-Type' => 'application/json')
puts "#{response.code} #{response.body}"
Bash cURL
curl.se
curl --request POST \
--url https://portal.bulkgate.com/api/2.0/advanced/promotional \
--header 'Content-Type: application/json' \
--data '{"application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "groups": [974, 975], "text": "Hello <first_name>, spring sale starts today.", "duplicates_check": "same_number", "channel": {"sms": {"sender_id": "gText", "sender_id_value": "BulkGate"}}}'
Byla tato stránka užitečná?
Děkujeme za zpětnou vazbu.