Libraries: Node.js, PHP and Laravel, Postman

Small official clients that handle authentication, errors, safe retries and webhook signatures. For anything they do not wrap, each has a generic request() that reaches every endpoint.

Node.js

Node.js 18 or newer, no dependencies, TypeScript types included.

Shell

npm install https://chatkomodo.com/sdk/chatkomodo-0.1.0.tgz

The packages are served from chatkomodo.com (checksums in SHA256SUMS).

Node.js

import { ChatKomodo, parseWebhook } from 'chatkomodo';

const ck = new ChatKomodo({ apiKey: process.env.CHATKOMODO_API_KEY });

const [device] = await ck.devices.list();
const sent = await ck.messages.send(device.id, {
  chat_id: '+447700900123',
  type: 'text',
  body: 'Your order #1042 has shipped',
}, { idempotencyKey: 'order-1042-shipped' });

// any other endpoint
const { contacts } = await ck.request('GET', '/v1/contacts', { query: { tag: 'vip' } });

// webhooks (Express): verify the raw body, then use the event
app.post('/webhooks/chatkomodo', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try { event = parseWebhook(req.body, req.get('X-Webhook-Signature'), process.env.CHATKOMODO_WEBHOOK_SECRET); }
  catch { return res.status(401).end(); }
  res.status(200).end();
});

PHP

PHP 8.1 or newer, Guzzle 7.

Shell

composer config repositories.chatkomodo composer https://chatkomodo.com/sdk/composer
composer require chatkomodo/chatkomodo-php

PHP

<?php
$ck = new \ChatKomodo\Client(getenv('CHATKOMODO_API_KEY'));

$sent = $ck->sendMessage($deviceId, [
    'chat_id' => '+447700900123',
    'type' => 'text',
    'body' => 'Your order #1042 has shipped',
], 'order-1042-shipped');

// webhooks
$raw = file_get_contents('php://input');
if (!\ChatKomodo\Webhook::verify($raw, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? null, getenv('CHATKOMODO_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

Laravel

The same package registers itself in Laravel. Put the key, the default sending device and the webhook secret in .env:

.env

CHATKOMODO_API_KEY=your-api-key
CHATKOMODO_DEVICE_ID=your-device-id
CHATKOMODO_WEBHOOK_SECRET=your-webhook-secret

Laravel

use ChatKomodo\Laravel\Facades\ChatKomodo;

ChatKomodo::sendText('+447700900123', 'Your order #1042 has shipped', "order-{$order->id}-shipped");

// routes/web.php (exclude the path from CSRF): the middleware answers 401 to unsigned deliveries
Route::post('/webhooks/chatkomodo', ChatKomodoWebhookController::class)->middleware('chatkomodo.webhook');

What the libraries do for you

Errors become exceptions with the HTTP status, the error code and, on 429, retryAfter (see Errors).
Retries: a 429 is retried after Retry-After; server and network errors are retried for reads, PUT and DELETE, and for a POST only when you pass an idempotency key (otherwise the message might be sent twice). Two retries by default.
Test devices: createTestDevice() and simulateInbound() wrap the sandbox.

Download the Postman collection (every endpoint, grouped like this reference, with an example request each) and import it. Set the collection variables apiKey and deviceId; baseUrl is already https://api.chatkomodo.com. It is rebuilt from the API description with every release.

Other languages

Any HTTP client works: every page of the reference has cURL, Node.js, Python and PHP examples. To generate a client, use the OpenAPI 3.1 document.