SDKs & code samples

Status: official SDKs (npm, composer, pip, etc.) are on the roadmap. For now, the API is simple enough that 20-50 lines of helper code in your language is all you need. Code below is production-ready — copy into your project and adapt.

Why not official SDKs yet

The GoSendAPI API is:

REST + JSON only
1 auth header (X-API-Key)
Standard HTTP semantics (status codes, retries, idempotency)

A generic HTTP client (axios, requests, Guzzle, http.Client) wraps it well. Premature SDKs add maintenance burden without much benefit until the API is large enough. We’ll publish official packages once the API surface stabilizes — probably after Q3 2026.

For now, the code below gives you a clean abstraction that’s 80% of what an SDK would do.

Helper classes

// lib/gosendapi.ts
const BASE_URL = 'https://cloud.gosendapi.com/v1';
 
export interface MessagePayload {
  phone_number_id: string;
  to: string;
  type: 'text' | 'template' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'interactive' | 'contacts';
  [key: string]: unknown;
}
 
export class GoSendAPIError extends Error {
  constructor(public statusCode: number, public body: unknown) {
    super(`GoSendAPI error ${statusCode}`);
  }
}
 
export class GoSendAPI {
  constructor(private apiKey: string, private baseUrl: string = BASE_URL) {}
 
  private async request<T>(
    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
    path: string,
    body?: unknown,
    idempotencyKey?: string,
  ): Promise<T> {
    const headers: Record<string, string> = {
      'X-API-Key': this.apiKey,
      'Content-Type': 'application/json',
    };
    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
 
    const res = await fetch(`${this.baseUrl}${path}`, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
 
    if (!res.ok) {
      const errorBody = await res.json().catch(() => ({}));
      throw new GoSendAPIError(res.status, errorBody);
    }
 
    return res.json() as Promise<T>;
  }
 
  // ─── Messages ──────────────────────────────────────────────
  sendMessage(payload: MessagePayload, idempotencyKey?: string) {
    return this.request('POST', '/messages', payload, idempotencyKey);
  }
 
  sendText(phoneNumberId: string, to: string, body: string, idempotencyKey?: string) {
    return this.sendMessage({
      phone_number_id: phoneNumberId,
      to,
      type: 'text',
      text: { body },
    }, idempotencyKey);
  }
 
  sendTemplate(
    phoneNumberId: string,
    to: string,
    templateName: string,
    languageCode: string,
    components: unknown[],
    idempotencyKey?: string,
  ) {
    return this.sendMessage({
      phone_number_id: phoneNumberId,
      to,
      type: 'template',
      template: { name: templateName, language: { code: languageCode }, components },
    }, idempotencyKey);
  }
 
  // ─── Listing ───────────────────────────────────────────────
  listMessages(filters: Record<string, string | number> = {}) {
    const params = new URLSearchParams(filters as Record<string, string>).toString();
    return this.request('GET', `/messages?${params}`);
  }
 
  listWabas() {
    return this.request('GET', '/wabas');
  }
 
  // ─── Templates ─────────────────────────────────────────────
  listTemplates(wabaId: string) {
    return this.request('GET', `/wabas/${wabaId}/templates`);
  }
 
  syncTemplates(wabaId: string) {
    return this.request('POST', `/wabas/${wabaId}/templates/sync`);
  }
 
  // ─── Webhooks ──────────────────────────────────────────────
  listWebhooks() {
    return this.request('GET', '/webhooks');
  }
 
  createWebhook(config: {
    url: string;
    events: string[];
    type?: 'gosendapi_events' | 'meta_raw';
    phone_number_id?: string;
  }) {
    return this.request('POST', '/webhooks', config);
  }
 
  // ─── Self ──────────────────────────────────────────────────
  me() {
    return this.request('GET', '/me');
  }
}
 
// Usage:
// const client = new GoSendAPI(process.env.GOSENDAPI_KEY!);
// await client.sendText('555123456789', '5491140123456', 'Hello!');

Webhook verification (Express):

// lib/verify-webhook.ts
import crypto from 'node:crypto';
import type { Request } from 'express';
 
export function verifyWebhook(req: Request, secret: string): boolean {
  const signature = req.header('X-GoSendAPI-Signature') ?? '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)  // Must be raw bytes! Use express.raw()
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

<?php
// lib/GoSendAPI.php
 
class GoSendAPIError extends Exception {
    public int $statusCode;
    public mixed $body;
    public function __construct(int $statusCode, mixed $body) {
        $this->statusCode = $statusCode;
        $this->body = $body;
        parent::__construct("GoSendAPI error {$statusCode}");
    }
}
 
class GoSendAPI {
    private string $apiKey;
    private string $baseUrl;
 
    public function __construct(string $apiKey, string $baseUrl = 'https://cloud.gosendapi.com/v1') {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }
 
    private function request(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null): array {
        $ch = curl_init($this->baseUrl . $path);
 
        $headers = [
            "X-API-Key: {$this->apiKey}",
            'Content-Type: application/json',
        ];
        if ($idempotencyKey) {
            $headers[] = "Idempotency-Key: {$idempotencyKey}";
        }
 
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
        ]);
 
        if ($body !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        }
 
        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
 
        $parsed = json_decode($response, true);
 
        if ($statusCode < 200 || $statusCode >= 300) {
            throw new GoSendAPIError($statusCode, $parsed);
        }
 
        return $parsed;
    }
 
    public function sendText(string $phoneNumberId, string $to, string $body, ?string $idempotencyKey = null): array {
        return $this->request('POST', '/messages', [
            'phone_number_id' => $phoneNumberId,
            'to' => $to,
            'type' => 'text',
            'text' => ['body' => $body],
        ], $idempotencyKey);
    }
 
    public function sendTemplate(string $phoneNumberId, string $to, string $name, string $language, array $components, ?string $idempotencyKey = null): array {
        return $this->request('POST', '/messages', [
            'phone_number_id' => $phoneNumberId,
            'to' => $to,
            'type' => 'template',
            'template' => [
                'name' => $name,
                'language' => ['code' => $language],
                'components' => $components,
            ],
        ], $idempotencyKey);
    }
 
    public function listMessages(array $filters = []): array {
        $query = http_build_query($filters);
        return $this->request('GET', "/messages?{$query}");
    }
 
    public function listWabas(): array { return $this->request('GET', '/wabas'); }
    public function listTemplates(string $wabaId): array { return $this->request('GET', "/wabas/{$wabaId}/templates"); }
    public function syncTemplates(string $wabaId): array { return $this->request('POST', "/wabas/{$wabaId}/templates/sync"); }
    public function me(): array { return $this->request('GET', '/me'); }
}
 
// Usage:
// $client = new GoSendAPI(getenv('GOSENDAPI_KEY'));
// $client->sendText('555123456789', '5491140123456', 'Hello!');

Webhook verification:

<?php
function verifyWebhook(string $rawBody, string $signature, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}
 
// Usage in handler:
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GOSENDAPI_SIGNATURE'] ?? '';
if (!verifyWebhook($rawBody, $signature, getenv('WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit('Invalid signature');
}

# lib/gosendapi.py
import os
import hmac
import hashlib
from typing import Any
import requests
 
BASE_URL = 'https://cloud.gosendapi.com/v1'
 
 
class GoSendAPIError(Exception):
    def __init__(self, status_code: int, body: Any):
        self.status_code = status_code
        self.body = body
        super().__init__(f'GoSendAPI error {status_code}')
 
 
class GoSendAPI:
    def __init__(self, api_key: str, base_url: str = BASE_URL):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({'X-API-Key': api_key, 'Content-Type': 'application/json'})
 
    def _request(self, method: str, path: str, body: dict | None = None, idempotency_key: str | None = None) -> dict:
        headers = {}
        if idempotency_key:
            headers['Idempotency-Key'] = idempotency_key
 
        res = self.session.request(method, f'{self.base_url}{path}', json=body, headers=headers, timeout=30)
 
        if not res.ok:
            try:
                error_body = res.json()
            except ValueError:
                error_body = res.text
            raise GoSendAPIError(res.status_code, error_body)
 
        return res.json()
 
    # ─── Messages ──────────────────────────────────────────────
    def send_text(self, phone_number_id: str, to: str, body: str, idempotency_key: str | None = None) -> dict:
        return self._request('POST', '/messages', {
            'phone_number_id': phone_number_id,
            'to': to,
            'type': 'text',
            'text': {'body': body},
        }, idempotency_key)
 
    def send_template(self, phone_number_id: str, to: str, name: str, language: str, components: list, idempotency_key: str | None = None) -> dict:
        return self._request('POST', '/messages', {
            'phone_number_id': phone_number_id,
            'to': to,
            'type': 'template',
            'template': {'name': name, 'language': {'code': language}, 'components': components},
        }, idempotency_key)
 
    # ─── Listing ───────────────────────────────────────────────
    def list_messages(self, **filters) -> dict:
        return self._request('GET', f'/messages?{requests.compat.urlencode(filters)}')
 
    def list_wabas(self) -> list:
        return self._request('GET', '/wabas')
 
    # ─── Templates ─────────────────────────────────────────────
    def list_templates(self, waba_id: str) -> list:
        return self._request('GET', f'/wabas/{waba_id}/templates')
 
    def sync_templates(self, waba_id: str) -> dict:
        return self._request('POST', f'/wabas/{waba_id}/templates/sync')
 
    # ─── Webhooks ──────────────────────────────────────────────
    def list_webhooks(self) -> list:
        return self._request('GET', '/webhooks')
 
    def create_webhook(self, url: str, events: list, **kwargs) -> dict:
        return self._request('POST', '/webhooks', {'url': url, 'events': events, **kwargs})
 
    # ─── Self ──────────────────────────────────────────────────
    def me(self) -> dict:
        return self._request('GET', '/me')
 
 
# Usage:
# client = GoSendAPI(os.environ['GOSENDAPI_KEY'])
# client.send_text('555123456789', '5491140123456', 'Hello!')
 
 
def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    """Verify webhook signature using HMAC-SHA256."""
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

// pkg/gosendapi/client.go
package gosendapi
 
import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"time"
)
 
const DefaultBaseURL = "https://cloud.gosendapi.com/v1"
 
type APIError struct {
	StatusCode int
	Body       any
}
 
func (e *APIError) Error() string {
	return fmt.Sprintf("gosendapi: %d", e.StatusCode)
}
 
type Client struct {
	APIKey  string
	BaseURL string
	HTTP    *http.Client
}
 
func NewClient(apiKey string) *Client {
	return &Client{
		APIKey:  apiKey,
		BaseURL: DefaultBaseURL,
		HTTP:    &http.Client{Timeout: 30 * time.Second},
	}
}
 
func (c *Client) request(method, path string, body any, idempotencyKey string) (json.RawMessage, error) {
	var bodyReader io.Reader
	if body != nil {
		b, err := json.Marshal(body)
		if err != nil {
			return nil, err
		}
		bodyReader = bytes.NewReader(b)
	}
 
	req, err := http.NewRequest(method, c.BaseURL+path, bodyReader)
	if err != nil {
		return nil, err
	}
	req.Header.Set("X-API-Key", c.APIKey)
	req.Header.Set("Content-Type", "application/json")
	if idempotencyKey != "" {
		req.Header.Set("Idempotency-Key", idempotencyKey)
	}
 
	res, err := c.HTTP.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
 
	respBody, _ := io.ReadAll(res.Body)
 
	if res.StatusCode < 200 || res.StatusCode >= 300 {
		var parsed any
		_ = json.Unmarshal(respBody, &parsed)
		return nil, &APIError{StatusCode: res.StatusCode, Body: parsed}
	}
 
	return respBody, nil
}
 
func (c *Client) SendText(phoneNumberID, to, body, idempotencyKey string) (json.RawMessage, error) {
	return c.request("POST", "/messages", map[string]any{
		"phone_number_id": phoneNumberID,
		"to":              to,
		"type":            "text",
		"text":            map[string]string{"body": body},
	}, idempotencyKey)
}
 
func (c *Client) ListMessages(filters url.Values) (json.RawMessage, error) {
	return c.request("GET", "/messages?"+filters.Encode(), nil, "")
}
 
func (c *Client) Me() (json.RawMessage, error) {
	return c.request("GET", "/me", nil, "")
}
 
// VerifyWebhook checks if the signature matches the body.
// Use this in your webhook handler before processing.
func VerifyWebhook(rawBody []byte, signature, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

Recommended HTTP client setup

Regardless of language, your HTTP client should:

Set a timeout (30s is reasonable for sends — Meta sometimes takes 20+s)
Use connection pooling (don’t open a new TCP connection per request)
Configure retries with exponential backoff (see Error handling)
Log the delivery_id / response correlation for tracing

Testing your integration

We have a few tricks for testing without spending real Meta quota:

Sandbox API key

Use a gsk_test_* key — sends return synthetic responses (no Meta call, no real delivery, no cost). The response includes _sandbox: true and status: "sent_sandbox" so you can distinguish in tests. Your integration code (HTTP, idempotency, retry) works identically to live mode.

Health check

Verify your auth setup:

curl https://cloud.gosendapi.com/v1/me -H "X-API-Key: $GOSENDAPI_KEY"

If you get back { "id": "...", "name": "..." } → your key works.

Webhook testing locally

ngrok: ngrok http 3000 → use the public URL as your webhook
webhook.site: inspect what we POST without writing code
Console logging in delivery logs: visible in dashboard → Webhooks

Roadmap

When official SDKs launch they’ll be at:

Language	Package	Status
Node.js / TypeScript	`npm i @gosendapi/sdk`	Planned Q3 2026
PHP	`composer require gosendapi/sdk`	Planned Q3 2026
Python	`pip install gosendapi`	Planned Q4 2026
Go	`go get github.com/gosendapi/sdk-go`	Planned Q4 2026
Ruby	`gem install gosendapi`	TBD

Want one prioritized? Vote at hello@gosendapi.com with your language and use case.

What’s next

Interactive endpoint explorer with full schemas

API Reference

Advanced patterns (templates, interactive, media reuse)

Sending messages

HMAC verification in 4 languages

Webhooks

API Reference Pricing