Withallo PHP SDK

composer require qrcommunication/withallo-sdk

<?php

use QrCommunication\Withallo\AlloClient;
use QrCommunication\Withallo\AlloClientOptions;
use QrCommunication\Withallo\Dto\CreateContactInput;
use QrCommunication\Withallo\Dto\CreateWebhookInput;
use QrCommunication\Withallo\Dto\SendSmsInput;
use QrCommunication\Withallo\Dto\SendSmsFranceInput;
use QrCommunication\Withallo\Enum\WebhookTopic;
use QrCommunication\Withallo\Exception\AlloApiException;

$allo = new AlloClient(new AlloClientOptions(
    apiKey: $_ENV['ALLO_API_KEY'],
));

// ── Lister les numéros connectés ─────────────────────────────────

foreach ($allo->numbers->list() as $n) {
    echo "{$n->name} — {$n->number} ({$n->country})\n";
}

// ── Envoyer un SMS (US / international) ─────────────────────────

$sms = $allo->sms->send(new SendSmsInput(
    from: '+1234567890',
    to: '+0987654321',
    message: 'Hello from Allo',
));
echo $sms->content . ' @ ' . $sms->startDate->format(DATE_ATOM) . "\n";

// ── Envoyer un SMS depuis la France (sender_id pré-vérifié) ─────

$allo->sms->sendFrance(new SendSmsFranceInput(
    senderId: 'MyCompany',
    to: '+33612345678',
    message: 'Bonjour depuis Allo',
));

// ── Rechercher l'historique des appels ──────────────────────────

$calls = $allo->calls->search(
    alloNumber: '+1234567890',
    page: 0,
    size: 20,
);
foreach ($calls->results as $call) {
    echo "{$call->type->value} {$call->fromNumber} → {$call->toNumber} "
       . "({$call->lengthInMinutes} min)\n";
}

// ── Créer puis récupérer un contact ─────────────────────────────

try {
    $contact = $allo->contacts->create(new CreateContactInput(
        numbers: ['+33612345678'],
        name: 'Jean',
        lastName: 'Dupont',
        emails: ['jean.dupont@example.com'],
    ));

    $fetched = $allo->contacts->get($contact->id);
    echo "{$fetched->name} {$fetched->lastName}\n";
} catch (AlloApiException $e) {
    echo "Allo error [{$e->code}] : {$e->getMessage()}\n";
}

// ── Souscrire un webhook aux événements CALL_RECEIVED + SMS_RECEIVED ──

$webhook = $allo->webhooks->create(new CreateWebhookInput(
    alloNumber: '+1234567890',
    url: 'https://example.com/webhooks/allo',
    topics: [WebhookTopic::CALL_RECEIVED, WebhookTopic::SMS_RECEIVED],
    enabled: true,
));
echo "Webhook id : {$webhook->id}\n";

use QrCommunication\Withallo\AlloClientOptions;

$options = new AlloClientOptions(
    apiKey:  $_ENV['ALLO_API_KEY'],                // Required — raw key, NO Bearer prefix
    baseUrl: 'https://api.withallo.com/v1/api',    // Default
    timeout: 30.0,                                 // Guzzle timeout in seconds
    headers: ['X-App-Name' => 'my-application'],   // Extra HTTP headers
);

namespace QrCommunication\Withallo\Enum;

enum WebhookTopic: string {
    case CALL_RECEIVED    = 'CALL_RECEIVED';
    case SMS_RECEIVED     = 'SMS_RECEIVED';
    case CONTACT_CREATED  = 'CONTACT_CREATED';
    case CONTACT_UPDATED  = 'CONTACT_UPDATED';
}

enum CallDirection: string {
    case INBOUND  = 'INBOUND';
    case OUTBOUND = 'OUTBOUND';
}

enum CallResult: string {
    case ANSWERED             = 'ANSWERED';
    case VOICEMAIL            = 'VOICEMAIL';
    case TRANSFERRED_AI       = 'TRANSFERRED_AI';
    case TRANSFERRED_EXTERNAL = 'TRANSFERRED_EXTERNAL';
    case BLOCKED              = 'BLOCKED';
    case FAILED               = 'FAILED';
}

enum TranscriptSource: string {
    case AGENT    = 'AGENT';
    case EXTERNAL = 'EXTERNAL';
    case USER     = 'USER';
}

enum ConversationEntryType: string {
    case CALL         = 'CALL';
    case TEXT_MESSAGE = 'TEXT_MESSAGE';
}

use QrCommunication\Withallo\Webhook\WebhookReceiver;
use QrCommunication\Withallo\Webhook\Payload\CallReceivedPayload;
use QrCommunication\Withallo\Webhook\Payload\SmsReceivedPayload;
use QrCommunication\Withallo\Webhook\Payload\ContactEventPayload;

$receiver = (new WebhookReceiver())
    ->allowedAlloNumbers(['+1234567890'])
    ->onCallReceived(function (CallReceivedPayload $p): void {
        // Persist, notify, enqueue transcript analysis…
    })
    ->onSmsReceived(function (SmsReceivedPayload $p): void {
        // …
    })
    ->onContactCreated(function (ContactEventPayload $p): void {
        // …
    })
    ->onContactUpdated(function (ContactEventPayload $p): void {
        // …
    });

// In your controller (Laravel example):
Route::post('/webhooks/allo/{token}', function (Request $request, string $token) use ($receiver) {
    if ($token !== config('services.allo.webhook_token')) {
        abort(404);
    }
    $receiver->handle($request->getContent());
    return response()->noContent();
});

use QrCommunication\Withallo\Exception\AlloApiException;

try {
    $allo->sms->sendFrance(new SendSmsFranceInput(
        senderId: 'Unverified',
        to: '+33612345678',
        message: 'Hi',
    ));
} catch (AlloApiException $e) {
    echo "HTTP {$e->status} — code={$e->code} — {$e->getMessage()}\n";

    foreach ($e->details as $detail) {
        echo "  · {$detail->field} : {$detail->message}\n";
    }

    match ($e->code) {
        'API_KEY_INVALID'            => /* 401 */ null,
        'API_KEY_INSUFFICIENT_SCOPE' => /* 403 */ null,
        'RATE_LIMITED'               => /* 429 — respect Retry-After */ null,
        'INVALID_SENDER_ID'          => /* 400 France */ null,
        default                      => throw $e,
    };
}

bash vendor/qrcommunication/withallo-sdk/skill/install.sh