PHPackages                             qrcommunication/withallo-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. qrcommunication/withallo-sdk

ActiveLibrary[API Development](/categories/api)

qrcommunication/withallo-sdk
============================

PHP SDK for Withallo (Allo) API — webhooks, calls, contacts, SMS and phone numbers

v0.2.1(2w ago)00MITPHPPHP ^8.2CI passing

Since Apr 14Pushed 2w agoCompare

[ Source](https://github.com/QrCommunication/sdk-withallo-php)[ Packagist](https://packagist.org/packages/qrcommunication/withallo-sdk)[ Docs](https://github.com/QrCommunication/sdk-withallo-php)[ RSS](/packages/qrcommunication-withallo-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (4)Versions (4)Used By (0)

Withallo SDK — PHP
==================

[](#withallo-sdk--php)

[![Version](https://camo.githubusercontent.com/3fb4be5dc3c1df885e1ba26b96adcd365a07351f276a4a4370e36a07906260a1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d302e312e302d626c75652e737667)](https://github.com/QrCommunication/sdk-withallo-php/releases)[![PHP 8.2+](https://camo.githubusercontent.com/c2588b5670f2c910b8cc849ace22a22efda8956b7c2f797d11d2096bbfc7b1f5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3737374242342e737667)](https://php.net)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Packagist](https://camo.githubusercontent.com/f37865ab78432506c331dbf124df961212e24ad950b64e681744ab41176a2321/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5061636b61676973742d7172636f6d6d756e69636174696f6e25324677697468616c6c6f2d2d73646b2d6f72616e67652e737667)](https://packagist.org/packages/qrcommunication/withallo-sdk)[![Tests](https://github.com/QrCommunication/sdk-withallo-php/actions/workflows/tests.yml/badge.svg)](https://github.com/QrCommunication/sdk-withallo-php/actions/workflows/tests.yml)

SDK PHP complet pour l'API [Withallo (Allo)](https://help.withallo.com/en/api-reference/introduction). Couvre les 5 domaines de l'API publique : **Webhooks**, **Calls**, **Contacts**, **SMS**, **Phone Numbers**. Inclut un **WebhookReceiver** pour traiter les payloads entrants (`CALL_RECEIVED`, `SMS_RECEIVED`, `CONTACT_CREATED`, `CONTACT_UPDATED`).

**PHP 8.2+** requis. Compatible Laravel, Symfony ou tout projet PHP.

---

Table des matières / Table of contents
--------------------------------------

[](#table-des-matières--table-of-contents)

- [Installation](#installation)
- [Démarrage rapide / Quick start](#d%C3%A9marrage-rapide--quick-start)
- [Référence des ressources / Resources reference](#r%C3%A9f%C3%A9rence-des-ressources--resources-reference)
    - [Webhooks — gestion](#1-webhooks--clientwebhooks)
    - [WebhookReceiver — réception](#2-webhookreceiver--r%C3%A9ception-des-%C3%A9v%C3%A9nements)
    - [Calls](#3-calls--clientcalls)
    - [Contacts](#4-contacts--clientcontacts)
    - [SMS](#5-sms--clientsms)
    - [Phone Numbers](#6-phone-numbers--clientphonenumbers)
- [Gestion d'erreurs / Error handling](#gestion-derreurs--error-handling)
- [Sécurité des webhooks / Webhook security](#s%C3%A9curit%C3%A9-des-webhooks--webhook-security)
- [Développement / Development](#d%C3%A9veloppement--development)

---

Installation
------------

[](#installation)

```
composer require qrcommunication/withallo-sdk
```

**Prérequis / Requirements** : PHP 8.2+, extensions `json` et `curl`.

Générez votre clé API depuis [web.withallo.com/settings/api](https://web.withallo.com/settings/api).

---

Démarrage rapide / Quick start
------------------------------

[](#démarrage-rapide--quick-start)

```
use QrCommunication\Withallo\WithalloClient;
use QrCommunication\Withallo\Enums\WebhookTopic;

$client = new WithalloClient(apiKey: 'your-api-key');

// Créer un webhook / Create a webhook
$webhook = $client->webhooks->create(
    alloNumber: '+1234567890',
    url: 'https://example.com/webhooks/allo',
    topics: [
        WebhookTopic::CALL_RECEIVED,
        WebhookTopic::SMS_RECEIVED,
    ],
);

// Envoyer un SMS (US) / Send SMS (US)
$client->sms->send(
    from: '+1234567890',
    to: '+0987654321',
    message: 'Hello from Withallo SDK',
);

// Envoyer un SMS France (sender ID verifié requis)
$client->sms->sendFrance(
    senderId: 'MyCompany',
    to: '+33612345678',
    message: 'Bonjour depuis le SDK Withallo',
);

// Lire un contact / Get a contact
$contact = $client->contacts->get('cnt_abc123');

// Rechercher l'historique d'appels / Search calls
$result = $client->calls->search(alloNumber: '+1234567890', size: 50);

// Tester la connexion / Test connectivity
$client->testConnection(); // true | false
```

---

Référence des ressources / Resources reference
----------------------------------------------

[](#référence-des-ressources--resources-reference)

### Architecture

[](#architecture)

```
WithalloClient
 ├─ webhooks       → Webhooks          (scope: WEBHOOKS_READ_WRITE)
 ├─ calls          → Calls             (scope: CONVERSATIONS_READ)
 ├─ contacts       → Contacts          (scope: CONTACTS_READ / CONTACTS_READ_WRITE)
 ├─ sms            → Sms               (scope: SMS_SEND)
 ├─ phoneNumbers   → PhoneNumbers      (scope: CONVERSATIONS_READ)
 └─ webhookReceiver() → WebhookReceiver (no network — parses incoming payloads)

```

---

### 1. Webhooks — `$client->webhooks`

[](#1-webhooks--client-webhooks)

Gère les abonnements webhook configurés sur votre compte Allo.

#### `list()` — liste les webhooks

[](#list--liste-les-webhooks)

```
/** @return list */
$webhooks = $client->webhooks->list();
// [
//   ['allo_number' => '+1234567890', 'enabled' => true, 'url' => '...', 'topics' => [...]],
//   ...
// ]
```

#### `create()` — crée un webhook

[](#create--crée-un-webhook)

```
$webhook = $client->webhooks->create(
    alloNumber: '+1234567890',
    url: 'https://example.com/webhooks/allo',
    topics: [WebhookTopic::CALL_RECEIVED, WebhookTopic::SMS_RECEIVED],
    enabled: true, // optionnel, défaut true
);
// => ['id' => 'web-abc', 'alloNumber' => '+...', 'enabled' => true, 'url' => '...', 'topics' => [...]]
```

#### `delete()` — supprime un webhook

[](#delete--supprime-un-webhook)

```
$client->webhooks->delete('web-2NfDKEm9sF8xK3pQr1Zt');
```

---

### 2. WebhookReceiver — réception des événements

[](#2-webhookreceiver--réception-des-événements)

Parse les payloads entrants dans votre contrôleur et dispatch vers les handlers.

```
use QrCommunication\Withallo\Webhooks\WebhookReceiver;
use QrCommunication\Withallo\Webhooks\WebhookEvent;
use QrCommunication\Withallo\Enums\WebhookTopic;

$receiver = new WebhookReceiver;

$receiver
    ->on(WebhookTopic::CALL_RECEIVED, function (WebhookEvent $e) {
        $callId = $e->get('id');
        $summary = $e->get('one_sentence_summary');
        // ... votre logique métier
    })
    ->on(WebhookTopic::SMS_RECEIVED, function (WebhookEvent $e) {
        $content = $e->get('content');
        $direction = $e->get('direction'); // INBOUND | OUTBOUND
    })
    ->on(WebhookTopic::CONTACT_CREATED, fn (WebhookEvent $e) => /* ... */)
    ->on(WebhookTopic::CONTACT_UPDATED, fn (WebhookEvent $e) => /* ... */);

// Dans votre endpoint HTTP (Laravel, Symfony, bare PHP, etc.)
$rawBody = file_get_contents('php://input');
$event = $receiver->handle($rawBody); // parse + dispatch
return response('', 200); // toujours répondre 200 en moins de 30s
```

**Méthodes disponibles sur `WebhookEvent`** :

- `$event->topic` → `WebhookTopic`
- `$event->data` → `array` payload spécifique au topic
- `$event->raw` → `array` enveloppe complète
- `$event->isCall() / isSms() / isContactCreated() / isContactUpdated()` → `bool`
- `$event->get('path.to.field', default)` → accès dot-notation

---

### 3. Calls — `$client->calls`

[](#3-calls--client-calls)

```
$result = $client->calls->search(
    alloNumber: '+1234567890',    // requis
    contactNumber: '+0987654321', // optionnel
    page: 0,                      // défaut 0
    size: 10,                     // défaut 10, max 100
);

// $result['results']   → list
// $result['metadata']  → ['total_pages' => X, 'current_page' => Y]
```

---

### 4. Contacts — `$client->contacts`

[](#4-contacts--client-contacts)

```
// Lire un contact
$contact = $client->contacts->get('cnt_abc123');

// Rechercher (paginé)
$result = $client->contacts->search(page: 0, size: 20);

// Créer (numbers requis, au moins un)
$contact = $client->contacts->create(
    numbers: ['+15551234567'],
    name: 'John',
    lastName: 'Doe',
    jobTitle: 'CEO',
    website: 'https://acme.com',
    emails: ['john@acme.com'],
);

// Mettre à jour (PUT — emails/numbers remplacent l'existant)
$contact = $client->contacts->update('cnt_abc123', [
    'last_name' => 'Smith',
    'job_title' => 'CTO',
    'emails' => ['john@acme.com', 'j.smith@acme.com'],
]);

// Conversation avec un contact
$conversation = $client->contacts->searchConversation('cnt_abc123', page: 0, size: 20);
```

---

### 5. SMS — `$client->sms`

[](#5-sms--client-sms)

```
// États-Unis / International
$client->sms->send(
    from: '+1234567890',  // votre numéro Allo
    to: '+0987654321',
    message: 'Hello',
);

// France (Sender ID vérifié requis)
$client->sms->sendFrance(
    senderId: 'MyCompany', // 3-11 chars, A-Z/0-9, ou shortcode
    to: '+33612345678',
    message: 'Bonjour',
);
```

> **Note France** : les opérateurs français bloquent les SMS émis depuis des numéros mobiles standards. Vous devez obtenir un **Alphanumeric Sender ID** ou un **Short Code** auprès du support Allo avant utilisation.

---

### 6. Phone Numbers — `$client->phoneNumbers`

[](#6-phone-numbers--client-phonenumbers)

```
$numbers = $client->phoneNumbers->list();
// [
//   ['number' => '+1234567890', 'name' => 'Main Line', 'country' => 'US', 'is_shared_number' => false],
//   ...
// ]
```

---

Gestion d'erreurs / Error handling
----------------------------------

[](#gestion-derreurs--error-handling)

Toutes les exceptions héritent de `QrCommunication\Withallo\Exceptions\WithalloException`.

```
WithalloException (RuntimeException)
├── ApiException            → erreur HTTP générique (contient httpStatus, responseBody, getErrorCode(), getDetails())
│   ├── AuthenticationException → 401 (API_KEY_INVALID)
│   ├── ForbiddenException      → 403 (API_KEY_INSUFFICIENT_SCOPE) + requiredScopes(): list
│   ├── ValidationException     → 400/422 + errors(): array
│   ├── NotFoundException       → 404
│   └── RateLimitException      → 429 + retryAfterSeconds: ?int
└── InvalidWebhookPayloadException → payload webhook malformé (parse)

```

```
use QrCommunication\Withallo\Exceptions\ForbiddenException;
use QrCommunication\Withallo\Exceptions\RateLimitException;

try {
    $client->webhooks->create(/* ... */);
} catch (ForbiddenException $e) {
    $missing = $e->requiredScopes(); // ['WEBHOOKS_READ_WRITE']
    // ... demander à l'utilisateur d'ajouter le scope sur sa clé
} catch (RateLimitException $e) {
    sleep($e->retryAfterSeconds ?? 1);
    // ... retry
}
```

---

Sécurité des webhooks / Webhook security
----------------------------------------

[](#sécurité-des-webhooks--webhook-security)

> **Important** : au moment de la publication de ce SDK (avril 2026), la documentation publique de Withallo **ne spécifie aucun en-tête de signature HMAC** permettant de vérifier cryptographiquement l'origine des webhooks. Ce SDK valide la *forme* du payload mais ne peut pas authentifier l'expéditeur.

**Mesures de durcissement recommandées** en attendant une spécification officielle :

- Servez votre endpoint webhook **en HTTPS uniquement**.
- Utilisez une URL **secrète et non devinable** (token dans le path).
- Whitelist des **IPs egress Withallo** au niveau firewall si elles sont publiées.
- Rejettez les payloads dont le `allo_number` (ou `from_number` / `to_number`) **ne correspond pas à vos propres numéros** (récupérés via `$client->phoneNumbers->list()` au démarrage).
- Répondez `200 OK` en **moins de 30 secondes**, ou Withallo considèrera la livraison comme échouée.

Si Withallo publie un schéma de signature, une méthode `WebhookReceiver::verifySignature(string $rawBody, string $signatureHeader, string $secret)` sera ajoutée sans breaking change.

---

Documentation & exemples / Documentation & examples
-----------------------------------------------------------

[](#documentation--exemples--documentation--examples)

FichierContenu[`docs/openapi.yaml`](docs/openapi.yaml)Spécification **OpenAPI 3.1** complète de l'API Withallo (endpoints, schémas de payloads, erreurs, sécurité)[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)Schémas **mermaid** : layers, request lifecycle, pipeline webhook, hiérarchie d'exceptions, extension points[`docs/examples/LaravelWebhookController.php`](docs/examples/LaravelWebhookController.php)Contrôleur **Laravel** pour recevoir les webhooks Withallo[`docs/examples/LaravelSmsService.php`](docs/examples/LaravelSmsService.php)Service **Laravel** (retry rate-limit, broadcast)[`docs/examples/plain-php-webhook.php`](docs/examples/plain-php-webhook.php)Endpoint webhook **PHP natif** (sans framework)[`docs/examples/error-handling.php`](docs/examples/error-handling.php)Gestion d'erreurs exhaustive (rate-limit, scope, validation…)[`docs/examples/live-smoke-test.php`](docs/examples/live-smoke-test.php)Test end-to-end contre l'API réelle[`llms.txt`](llms.txt)Index au format [llmstxt.org](https://llmstxt.org) pour les LLMs / agents IA[`CLAUDE.md`](CLAUDE.md) / [`AGENTS.md`](AGENTS.md)Instructions pour outils IA (Claude, Cursor, Copilot, Codex)[`skill/SKILL.md`](skill/SKILL.md)Descripteur de skill Claude CodeDéveloppement / Development
---------------------------

[](#développement--development)

```
# Installer les dépendances
composer install

# Lancer les tests
composer test

# Analyse statique (PHPStan niveau 8)
composer analyse

# Formater le code (Laravel Pint)
composer lint
```

### Versioning et release

[](#versioning-et-release)

Ce package suit le [Semantic Versioning](https://semver.org/). Les versions sont publiées automatiquement sur Packagist via le webhook GitHub → Packagist lors de chaque tag `vX.Y.Z`. Le changelog est généré par [release-please](https://github.com/googleapis/release-please).

---

Licence / License
-----------------

[](#licence--license)

[MIT](LICENSE) © 2026 [QrCommunication](https://qrcommunication.com)

---

Liens / Links
-------------

[](#liens--links)

- [Documentation API Withallo (EN)](https://help.withallo.com/en/api-reference/introduction)
- [Documentation API Withallo (FR)](https://help.withallo.com/fr/api-reference/introduction)
- [SDK JavaScript / React](https://github.com/QrCommunication/sdk-withallo-js)
- [Packagist](https://packagist.org/packages/qrcommunication/withallo-sdk)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance97

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~40 days

Total

2

Last Release

15d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4362602?v=4)[Rony Licha](/maintainers/ronylicha)[@ronylicha](https://github.com/ronylicha)

---

Top Contributors

[![ronylicha](https://avatars.githubusercontent.com/u/4362602?v=4)](https://github.com/ronylicha "ronylicha (5 commits)")

---

Tags

apisdksmswebhookscontactscallswithalloallo

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/qrcommunication-withallo-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/qrcommunication-withallo-sdk/health.svg)](https://phpackages.com/packages/qrcommunication-withallo-sdk)
```

###  Alternatives

[resend/resend-php

Resend PHP library.

596.2M34](/packages/resend-resend-php)[clicksend/clicksend-php

351.6M11](/packages/clicksend-clicksend-php)[mozex/anthropic-laravel

Laravel integration for the Anthropic API: facade, config publishing, install command, testing fakes, messages, streaming, tool use, thinking, and batches.

74287.1k1](/packages/mozex-anthropic-laravel)[files.com/files-php-sdk

Files.com PHP SDK

2478.1k](/packages/filescom-files-php-sdk)[fingerprint/fingerprint-pro-server-api-sdk

Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device.

33250.3k1](/packages/fingerprint-fingerprint-pro-server-api-sdk)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

232.5k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)