How to Integrate RCS Business Messaging API in PHP (With Webhooks & Fallback)

Authorization: Bearer <YOUR_ACCESS_TOKEN>

curl -X POST "https://API_HOST/v1/messages" \
  -H "Authorization: Bearer $RCS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @rich-card.json

<?php
// rcs-client.php: a small helper for sending RCS messages over HTTPS.
declare(strict_types=1);

const RCS_API_BASE = 'https://API_HOST';       // from your onboarding pack

function sendRcs(array $payload): array
{
    $token = getenv('RCS_ACCESS_TOKEN');         // keep credentials out of source code
    if ($token === false || $token === '') {
        throw new RuntimeException('Set the RCS_ACCESS_TOKEN environment variable.');
    }

    $ch = curl_init(RCS_API_BASE . '/v1/messages');   // example path
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $token,
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
    ]);
    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $error  = curl_error($ch);
    curl_close($ch);

    if ($body === false) {
        throw new RuntimeException("Request failed: $error");
    }
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException("API returned HTTP $status");
    }
    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

<?php
require __DIR__ . '/rcs-client.php';

$richCard = [
    'to'          => '+91XXXXXXXXXX',
    'template_id' => 'YOUR_TEMPLATE_ID',        // an approved template
    'type'        => 'rich_card',
    'card'        => [
        'title'       => 'Your order #10234 is packed',
        'description' => 'Arriving Friday. Track it or pick another delivery slot.',
        'media'       => ['url' => 'https://example.com/images/order-10234.jpg', 'height' => 'MEDIUM'],
        'suggestions' => [
            ['type' => 'url',   'text' => 'Track order', 'url' => 'https://example.com/track/10234'],
            ['type' => 'reply', 'text' => 'Change slot', 'postback' => 'CHANGE_SLOT_10234'],
        ],
    ],
];

$result = sendRcs($richCard);
echo 'Accepted, message ID: ' . ($result['message_id'] ?? 'see response') . PHP_EOL;

<?php
require __DIR__ . '/rcs-client.php';

$products = [
    ['Running shoes', 'Sizes 6 to 11, free returns', 'https://example.com/img/shoes.jpg', 'SHOES'],
    ['Smart watch',   'Two-year warranty',           'https://example.com/img/watch.jpg', 'WATCH'],
    ['Backpack',      '30 litres, water resistant',  'https://example.com/img/bag.jpg',   'BAG'],
];

$carousel = [
    'to'          => '+91XXXXXXXXXX',
    'template_id' => 'YOUR_CAROUSEL_TEMPLATE_ID',
    'type'        => 'carousel',
    'card_width'  => 'MEDIUM',
    'cards'       => array_map(fn (array $p): array => [
        'title'       => $p[0],
        'description' => $p[1],
        'media'       => ['url' => $p[2], 'height' => 'MEDIUM'],
        'suggestions' => [
            ['type' => 'reply', 'text' => 'Buy now',      'postback' => 'BUY_' . $p[3]],
            ['type' => 'reply', 'text' => 'More details', 'postback' => 'INFO_' . $p[3]],
        ],
    ], $products),
];

$result = sendRcs($carousel);
echo 'Accepted, message ID: ' . ($result['message_id'] ?? 'see response') . PHP_EOL;

{
  "message_id": "MSG_ID_FROM_SEND_RESPONSE",
  "status": "DELIVERED",
  "timestamp": "2026-10-22T09:30:12Z"
}

<?php
// rcs-webhook.php: receives delivery-status callbacks and answers 200 OK.
declare(strict_types=1);

const KNOWN_STATUSES = ['DELIVERED', 'READ', 'FAILED'];   // map to your provider's values

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    http_response_code(405);
    header('Allow: POST');
    exit;
}

// Only trust callbacks from your provider. This example compares a shared secret sent in a
// header; use the check described in your onboarding pack.
$secret = getenv('RCS_WEBHOOK_SECRET') ?: '';
$given  = $_SERVER['HTTP_X_WEBHOOK_TOKEN'] ?? '';
if ($secret === '' || !hash_equals($secret, $given)) {
    http_response_code(401);
    exit;
}

try {
    $event = json_decode(file_get_contents('php://input') ?: '', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    http_response_code(400);
    exit;
}

$messageId = is_array($event) ? (string) ($event['message_id'] ?? '') : '';
$status    = is_array($event) ? strtoupper((string) ($event['status'] ?? '')) : '';

if ($messageId !== '' && in_array($status, KNOWN_STATUSES, true)) {
    saveStatus($messageId, $status);
    if ($status === 'FAILED') {
        queueSmsFallback($messageId);
    }
}

// Acknowledge quickly, even for statuses you don't use, so the provider stops retrying.
http_response_code(200);
header('Content-Type: text/plain');
echo 'OK';

function saveStatus(string $messageId, string $status): void
{
    // Upsert by message ID so a repeated callback is harmless. Log IDs and statuses only,
    // never phone numbers or message text.
    error_log("RCS status: $messageId $status");
}

function queueSmsFallback(string $messageId): void
{
    // Add a job to your queue. The worker sends the DLT-approved SMS (registered header and
    // template) only if the RCS message still hasn't been delivered.
}

<?php
// Decide whether a message should fall back to SMS.
function needsSmsFallback(?string $status, int $sentAt, int $now, int $waitSeconds = 600): bool
{
    if ($status === 'DELIVERED' || $status === 'READ') {
        return false;                        // RCS reached the phone
    }
    if ($status === 'FAILED') {
        return true;                         // for example, the handset doesn't support RCS
    }
    return $now - $sentAt >= $waitSeconds;   // no delivery in time: revoke the RCS message, then send SMS
}