Quick Reference

This page provides ready-to-use code examples for the most common SendSeven API operations. Replace the placeholder credentials with your own values.

Setup

All examples use these credentials:

API Token:  s7_api_a1b2c3d4e5f6789012345678abcdef00
Base URL:   https://api.sendseven.com/api/v1

Pagination

Most list endpoints return the unified envelope: an items array plus a pagination object.

{
  "items": [ /* ... */ ],
  "pagination": {
    "total": 142,
    "page": 1,
    "page_size": 20,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Page with page / page_size and stop when has_next is false. There is no next_page_url, no next link, and no Link header — page numbers are the only cursor.

def fetch_all(path, params=None):
    """Yield every item across all pages of a list endpoint."""
    params = dict(params or {})
    params.setdefault("page_size", 100)
    params["page"] = 1
    while True:
        data = requests.get(f"{BASE_URL}/{path}", headers=HEADERS, params=params).json()
        yield from data["items"]
        if not data["pagination"]["has_next"]:
            break
        params["page"] += 1

Three endpoints deviate

Do not assume the envelope everywhere — a few endpoints predate it:

Endpoint	Shape
`GET /whatsapp-templates`	`limit` / `offset`; returns `{"templates": [...], "total": n, ...}` — see Templates
`GET /webhook-endpoints`	A bare JSON array, unpaginated
`GET /webhook-endpoints/{id}/deliveries`	`items` plus flat `total` / `page` / `page_size` / `has_more` (no `pagination` object)

When in doubt, the OpenAPI spec is authoritative.

Error Handling

Always include proper error handling in your integration.

Python

import requests

def api_request(method, path, **kwargs):
    url = f"https://api.sendseven.com/api/v1{path}"
    headers = {
        "Authorization": "Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00",
        "Content-Type": "application/json",
    }

    response = requests.request(method, url, headers=headers, **kwargs)

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retry after {retry_after} seconds.")
        return None

    if not response.ok:
        error = response.json()
        print(f"Error {response.status_code}: {error.get('detail', 'Unknown error')}")
        print(f"Error code: {error.get('error_code', 'UNKNOWN')}")
        return None

    return response.json()

JavaScript

async function apiRequest(method, path, body = null) {
  const url = `https://api.sendseven.com/api/v1${path}`;
  const options = {
    method,
    headers: {
      "Authorization": "Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00",
      "Content-Type": "application/json",
    },
  };

  if (body) options.body = JSON.stringify(body);

  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || 60;
    console.log(`Rate limited. Retry after ${retryAfter} seconds.`);
    return null;
  }

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${response.status}: ${error.detail || "Unknown error"}`);
    return null;
  }

  return response.json();
}

Conversations

List Open Conversations

cURL
Python
JavaScript

curl -X GET "https://api.sendseven.com/api/v1/conversations?status=open&page=1&page_size=20" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

def list_conversations(status="open", page=1, page_size=20):
    response = requests.get(
        f"{BASE_URL}/conversations",
        headers=HEADERS,
        params={"status": status, "page": page, "page_size": page_size},
    )
    response.raise_for_status()
    data = response.json()

    print(f"Total conversations: {data['pagination']['total']}")
    for conv in data["items"]:
        print(f"  [{conv['channel_type']}] {conv['id']} - {conv['status']}")

    return data

async function listConversations(status = "open", page = 1, pageSize = 20) {
  const params = new URLSearchParams({ status, page, page_size: pageSize });
  const response = await fetch(`${BASE_URL}/conversations?${params}`, {
    headers: HEADERS,
  });
  const data = await response.json();
  console.log(`Total conversations: ${data.pagination.total}`);
  return data;
}

Assign a Conversation

curl -X PUT "https://api.sendseven.com/api/v1/conversations/conv_abc123" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to": "user_abc111"}'

Close a Conversation

curl -X POST "https://api.sendseven.com/api/v1/conversations/conv_abc123/close" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Issue resolved - customer received refund"}'

Messages

Send a Text Message

cURL
Python
JavaScript

curl -X POST "https://api.sendseven.com/api/v1/messages" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "text": "Hello! How can I help you today?",
    "message_type": "text"
  }'

def send_message(conversation_id, text, message_type="text"):
    response = requests.post(
        f"{BASE_URL}/messages",
        headers=HEADERS,
        json={
            "conversation_id": conversation_id,
            "text": text,
            "message_type": message_type,
        },
    )
    response.raise_for_status()
    message = response.json()
    print(f"Message sent: {message['id']}")
    return message

async function sendMessage(conversationId, text, messageType = "text") {
  const response = await fetch(`${BASE_URL}/messages`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
      conversation_id: conversationId,
      text: text,
      message_type: messageType,
    }),
  });
  const message = await response.json();
  console.log(`Message sent: ${message.id}`);
  return message;
}

Send a Message to a Contact

curl -X POST "https://api.sendseven.com/api/v1/messages" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_xyz789",
    "channel_id": "channel_wa_001",
    "text": "Your order has shipped!",
    "message_type": "text"
  }'

Send an Interactive Button Message

curl -X POST "https://api.sendseven.com/api/v1/messages/send/interactive" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "type": "buttons",
    "body": "How would you like to proceed?",
    "buttons": [
      {"id": "refund", "title": "Request Refund"},
      {"id": "exchange", "title": "Exchange Item"},
      {"id": "help", "title": "More Help"}
    ]
  }'

Contacts

Create a Contact

cURL
Python
JavaScript

curl -X POST "https://api.sendseven.com/api/v1/contacts" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+14155559876",
    "custom_fields": {"company": "Acme Inc"}
  }'

def create_contact(name, email=None, phone=None, custom_fields=None):
    payload = {"name": name}
    if email:
        payload["email"] = email
    if phone:
        payload["phone"] = phone
    if custom_fields:
        payload["custom_fields"] = custom_fields

    response = requests.post(f"{BASE_URL}/contacts", headers=HEADERS, json=payload)
    response.raise_for_status()
    contact = response.json()
    print(f"Contact created: {contact['id']} - {contact['name']}")
    return contact

async function createContact(name, email, phone, customFields = {}) {
  const payload = { name };
  if (email) payload.email = email;
  if (phone) payload.phone = phone;
  if (Object.keys(customFields).length > 0) payload.custom_fields = customFields;

  const response = await fetch(`${BASE_URL}/contacts`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(payload),
  });
  return response.json();
}

Knowledge Base

Search

curl -X POST "https://api.sendseven.com/api/v1/knowledge-base/search" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I reset my password?", "limit": 5}'

Webhooks

Create a Webhook

curl -X POST "https://api.sendseven.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook",
    "events": ["message.received", "conversation.closed", "email.received"],
    "active": true
  }'

Handle a Webhook (Python/Flask)

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret_here"

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Webhook-Signature", "")
    if not verify_signature(request.data, signature):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json

    if event["type"] == "message.received":
        print(f"New message: {event['data']['message']['text']}")
    elif event["type"] == "conversation.closed":
        print(f"Closed: {event['data']['conversation_id']}")
    elif event["type"] == "email.received":
        print(f"Email from {event['data']['from_id']}: {event['data']['subject']}")

    return jsonify({"received": True}), 200

Handle a Webhook (JavaScript/Express)

const express = require("express");
const crypto = require("crypto");

const WEBHOOK_SECRET = "your_webhook_secret_here";
const app = express();

app.use(express.raw({ type: "application/json" }));

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature || ""))) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { type, data } = JSON.parse(req.body);

  switch (type) {
    case "message.received":
      console.log(`New message: ${data.message.text}`);
      break;
    case "conversation.closed":
      console.log(`Closed: ${data.conversation_id}`);
      break;
    case "email.received":
      console.log(`Email from ${data.from_id}: ${data.subject}`);
      break;
  }

  res.json({ received: true });
});

app.listen(3000, () => console.log("Webhook server running on port 3000"));

Attachments

Upload an Attachment

curl -X POST "https://api.sendseven.com/api/v1/attachments/upload" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -F "file=@/path/to/document.pdf" \
  -F "purpose=message"

Analytics

Get Dashboard Metrics

curl -X GET "https://api.sendseven.com/api/v1/analytics/dashboard?date_from=2026-02-01&date_to=2026-02-10" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

Setup​

Pagination​

Error Handling​

Python​

JavaScript​

Conversations​

List Open Conversations​

Assign a Conversation​

Close a Conversation​

Messages​

Send a Text Message​

Send a Message to a Contact​

Send an Interactive Button Message​

Contacts​

Create a Contact​

Knowledge Base​

Search​

Webhooks​

Create a Webhook​

Handle a Webhook (Python/Flask)​

Handle a Webhook (JavaScript/Express)​

Tags​

List Tags​

Attachments​

Upload an Attachment​

Analytics​

Get Dashboard Metrics​

Related Guides​