Mosend
MosendDeveloper

SDK PHP · Quickstart

moshipp/mosend-sdk es el SDK oficial de PHP — cero dependencias (solo ext-curl), PHP 7.4+, ideal para WooCommerce / hosting compartido. Los inputs son arrays asociativos. Ver todos los SDK →

1

Instalá e instanciá el cliente

composer
composer require moshipp/mosend-sdk
client.php
<?php
require 'vendor/autoload.php';

use Mosend\MosendClient;

$mosend = new MosendClient([
    'apiKey' => getenv('MOSEND_API_KEY'),   // mk_live_<prefix>.<secret>
    'orgId'  => getenv('MOSEND_ORG_ID'),    // default para rutas /organizations/{orgId}/...
    // opcionales:
    // 'retries' => ['max' => 3, 'on' => [429, 502, 503]],
    // 'timeout' => 30000,  // ms
]);

El cliente acepta API key (server-to-server) o un accessToken JWT. Con orgId en el constructor no lo repetís en cada llamada (igual podés pasarlo por método).

2

Enviá un mensaje o una plantilla

enviar.php
// Texto (ventana de 24h abierta)
$mosend->messages->send([
    'phoneNumberId' => '<phone-uuid>',
    'to'            => '573001234567',     // E.164 sin '+'
    'type'          => 'text',
    'payload'       => ['body' => 'Hola 👋'],
]);

// Plantilla (body posicional)
$msg = $mosend->messages->send([
    'phoneNumberId' => '<phone-uuid>',
    'to'            => '573001234567',
    'type'          => 'template',
    'templateId'    => '<uuid-de-la-plantilla>',
    'variables'     => ['Juan', 'FAC-2026-0042'],
]);
echo $msg['id'], ' ', $msg['metaMessageId'], PHP_EOL;

// Idempotencia (no duplica si reenviás el mismo key)
$mosend->messages->send([...], ['idempotencyKey' => 'order-42']);
3

Listá y paginá

Cada listado tiene list() (una página) e iterate() (un Generator que recorre todas las páginas por vos).

paginar.php
// Recorrer TODAS las conversaciones abiertas
foreach ($mosend->conversations->iterate(['status' => 'open']) as $conv) {
    echo $conv['id'], PHP_EOL;
}

// Contactos (paginación por página, manejada internamente)
foreach ($mosend->contacts->iterate(['q' => 'juan']) as $contact) {
    echo $contact['waId'], ' ', $contact['name'] ?? '', PHP_EOL;
}

// Una sola página
$page = $mosend->conversations->list(['status' => 'open', 'take' => 50]);
// $page['data'], $page['endCursor'], $page['hasNextPage']
4

Manejá errores tipados

Jerarquía de excepciones: MosendApiException y subclases por código HTTP (MosendAuthException, MosendRateLimitException, …), MosendNetworkException y MosendValidationException.

errores.php
use Mosend\Exception\MosendRateLimitException;
use Mosend\Exception\MosendApiException;
use Mosend\Exception\MosendNetworkException;

try {
    $mosend->messages->send([/* ... */]);
} catch (MosendRateLimitException $e) {
    error_log('rate limit; reintentar en ' . $e->getRetryAfterSec() . 's');
} catch (MosendApiException $e) {
    // 4xx/5xx; errores de Meta traen getMetaCode()/getMetaSubcode()
    error_log($e->getStatus() . ' ' . $e->getMessage() . ' meta=' . $e->getMetaCode());
} catch (MosendNetworkException $e) {
    error_log('falló la red/timeout: ' . $e->getMessage());
}
5

Verificá webhooks entrantes

Validá la firma HMAC sobre el body crudo antes de procesar. parseEvent valida y devuelve el evento como array.

webhook.php
<?php
use Mosend\Webhooks\WebhookVerifier;
use Mosend\Exception\MosendWebhookSignatureException;

$raw = file_get_contents('php://input');               // body CRUDO
$sig = $_SERVER['HTTP_X_MOSEND_SIGNATURE'] ?? null;

try {
    $event = WebhookVerifier::parseEvent($raw, $sig, getenv('MOSEND_WEBHOOK_SECRET'));
    // $event['event'] => 'message.new' | 'message.status' | ...
    // deduplicá por $event['deliveryId'] (puede reintentarse)
    http_response_code(200);
} catch (MosendWebhookSignatureException $e) {
    http_response_code(401);
}

Detalles del payload y eventos en webhooks salientes.

El SDK cubre los 57 módulos. Cualquier endpoint de la referencia (ej. /api/broadcasts) tiene su método equivalente: $mosend->broadcasts->create([...]), ->send($id), etc.