API Guide

Authentication

All API requests require authentication using your API key. Include your key in the X-API-Key header:

X-API-Key: cb_live_your_api_key_here

You can find your API key on your Account page after signing up.

Keep your API key secret. Never expose it in client-side code or public repositories.

POST Send WhatsApp Message

https://chatbridge.net/api/sendwhatsapp

Send a WhatsApp message to your registered phone number. The message will be delivered via WhatsApp Business API.

Request Body

Parameter	Type	Description
`message` Required	string	The message content to send
`session_id` Optional	string	Custom session ID for tracking. If omitted, server generates one.
`sys_name` Optional	string	Name of the system/agent sending the message (e.g., "Claude Code")

Example Request

curl -X POST https://chatbridge.net/api/sendwhatsapp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_your_api_key" \
  -d '{
    "message": "Should I deploy to production?",
    "sys_name": "Deploy Bot"
  }'

Response

{
  "success": true,
  "message_id": "wamid.xxx",
  "session_id": "afk-a1b2c3d4e5f6"
}

Response Codes

200 Message sent successfully

400 Bad request (missing message or invalid JSON)

401 Invalid or missing API key

429 Rate limit exceeded

POST Send SMS Message

https://chatbridge.net/api/sendsms

Send an SMS message to your registered phone number. Requires a subscription tier that includes SMS.

Request Body

Parameter	Type	Description
`message` Required	string	The message content to send
`session_id` Optional	string	Custom session ID for tracking. If omitted, server generates one.
`force_sms` Optional	boolean	If true, sends full message as multi-part SMS instead of a link for long messages

Long messages: Messages over 255 characters are automatically converted to a short link (chatbridge.net/go/...) unless force_sms is set to true.

Example Request

curl -X POST https://chatbridge.net/api/sendsms \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_your_api_key" \
  -d '{
    "message": "Build complete. Deploy to staging?",
    "force_sms": false
  }'

Response

{
  "success": true,
  "message_id": "sms-xxx",
  "session_id": "afk-a1b2c3d4e5f6"
}

Response Codes

200 Message sent successfully

400 Bad request (missing message or invalid JSON)

401 Invalid or missing API key

403 SMS not available on your subscription tier

429 Rate limit exceeded

GET Receive Responses (SSE)

https://chatbridge.net/api/events/{session_id}

Connect to a Server-Sent Events stream to receive real-time responses to your messages. Keep this connection open while waiting for a reply.

Path Parameters

Parameter	Type	Description
`session_id` Required	string	The session ID returned from the send message endpoint

Event Format

event: message
data: {"From":"+447...", "Content":"Yes, deploy it", "Timestamp":"2025-01-15T10:30:00Z"}

Example (curl)

curl -N https://chatbridge.net/api/events/afk-a1b2c3d4e5f6 \
  -H "X-API-Key: cb_live_your_api_key"

Connection: The SSE connection will remain open. Implement reconnection logic in production to handle network interruptions.

Webhooks (Fire & Forget)

For simple notifications where you don't need a response, use the API directly without waiting for SSE events. This is ideal for CI/CD pipelines, monitoring alerts, and batch notifications.

Fire-and-Forget Pattern

Send a message and move on immediately - no need to wait for a response:

# Simple notification - no response needed
curl -X POST https://chatbridge.net/api/sendwhatsapp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"message": "Build #142 completed successfully!", "sys_name": "CI Server"}'

# SMS alert
curl -X POST https://chatbridge.net/api/sendsms \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"message": "ALERT: CPU usage at 95%"}'

CI/CD Integration Examples

GitHub Actions

- name: Notify on deploy
  run: |
    curl -X POST https://chatbridge.net/api/sendwhatsapp \
      -H "Content-Type: application/json" \
      -H "X-API-Key: ${{ secrets.CHATBRIDGE_API_KEY }}" \
      -d '{"message": "Deployed ${{ github.sha }} to production", "sys_name": "GitHub Actions"}'

GitLab CI

notify:
  stage: .post
  script:
    - |
      curl -X POST https://chatbridge.net/api/sendwhatsapp \
        -H "Content-Type: application/json" \
        -H "X-API-Key: $CHATBRIDGE_API_KEY" \
        -d "{\"message\": \"Pipeline $CI_PIPELINE_ID completed\", \"sys_name\": \"GitLab CI\"}"
  when: on_success

Jenkins Pipeline

post {
    success {
        sh '''
            curl -X POST https://chatbridge.net/api/sendwhatsapp \
              -H "Content-Type: application/json" \
              -H "X-API-Key: ${CHATBRIDGE_API_KEY}" \
              -d '{"message": "Build succeeded: ${BUILD_URL}", "sys_name": "Jenkins"}'
        '''
    }
    failure {
        sh '''
            curl -X POST https://chatbridge.net/api/sendsms \
              -H "Content-Type: application/json" \
              -H "X-API-Key: ${CHATBRIDGE_API_KEY}" \
              -d '{"message": "BUILD FAILED: ${JOB_NAME}"}'
        '''
    }
}

Monitoring & Alerting

Integrate with your monitoring stack to receive critical alerts:

Prometheus Alertmanager

# alertmanager.yml
receivers:
  - name: 'chatbridge-sms'
    webhook_configs:
      - url: 'https://your-proxy.com/alert-to-chatbridge'
        send_resolved: true

# Your proxy endpoint translates to ChatBridge API:
curl -X POST https://chatbridge.net/api/sendsms \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"message": "FIRING: HighMemoryUsage on prod-server-1"}'

Simple Health Check Script

#!/bin/bash
# health-check.sh - run via cron

if ! curl -sf http://localhost:8080/health > /dev/null; then
    curl -X POST https://chatbridge.net/api/sendsms \
      -H "Content-Type: application/json" \
      -H "X-API-Key: $CHATBRIDGE_API_KEY" \
      -d '{"message": "ALERT: Service health check failed!"}'
fi

Batch Notifications

Send multiple notifications efficiently:

#!/bin/bash
# Send notifications to multiple endpoints

API_KEY="cb_live_your_api_key"
MESSAGE="Daily backup completed: 142GB processed"

# WhatsApp notification
curl -s -X POST https://chatbridge.net/api/sendwhatsapp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"message\": \"$MESSAGE\", \"sys_name\": \"Backup System\"}" &

# SMS notification (runs in parallel)
curl -s -X POST https://chatbridge.net/api/sendsms \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"message\": \"$MESSAGE\"}" &

wait  # Wait for both to complete

Tip: For fire-and-forget notifications, you can ignore the response. The message will be delivered even if you don't process the API response.

Rate Limits

API endpoints have rate limits to ensure fair usage:

Endpoint	Limit
`/api/sendwhatsapp`	60 requests per minute
`/api/sendsms`	60 requests per minute
`/api/events/*`	60 connections per minute

Exceeding these limits will result in a 429 Too Many Requests response.

Code Examples

Python

import requests
import sseclient

API_KEY = "cb_live_your_api_key"
BASE_URL = "https://chatbridge.net"

# Send a WhatsApp message
response = requests.post(
    f"{BASE_URL}/api/sendwhatsapp",
    headers={"X-API-Key": API_KEY},
    json={"message": "Deploy to production?", "sys_name": "Deploy Bot"}
)
data = response.json()
session_id = data["session_id"]

# Listen for responses
response = requests.get(
    f"{BASE_URL}/api/events/{session_id}",
    headers={"X-API-Key": API_KEY},
    stream=True
)
client = sseclient.SSEClient(response)
for event in client.events():
    if event.event == "message":
        print(f"Response: {event.data}")
        break

Node.js

const EventSource = require('eventsource');

const API_KEY = 'cb_live_your_api_key';
const BASE_URL = 'https://chatbridge.net';

// Send a WhatsApp message
const response = await fetch(`${BASE_URL}/api/sendwhatsapp`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    message: 'Deploy to production?',
    sys_name: 'Deploy Bot'
  })
});
const { session_id } = await response.json();

// Listen for responses
const es = new EventSource(`${BASE_URL}/api/events/${session_id}`, {
  headers: { 'X-API-Key': API_KEY }
});
es.addEventListener('message', (e) => {
  console.log('Response:', JSON.parse(e.data).Content);
  es.close();
});

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    apiKey := "cb_live_your_api_key"
    baseURL := "https://chatbridge.net"

    // Send WhatsApp message
    payload := map[string]string{
        "message":  "Deploy to production?",
        "sys_name": "Deploy Bot",
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", baseURL+"/api/sendwhatsapp", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Session ID: %s\n", result["session_id"])
}

Shell (Bash)

#!/bin/bash

API_KEY="cb_live_your_api_key"

# Send WhatsApp message
response=$(curl -s -X POST https://chatbridge.net/api/sendwhatsapp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"message": "Deploy to production?", "sys_name": "Deploy Bot"}')

session_id=$(echo $response | jq -r '.session_id')
echo "Session ID: $session_id"

# Listen for response (streams until interrupted)
curl -N "https://chatbridge.net/api/events/$session_id" \
  -H "X-API-Key: $API_KEY"

Need Help?

Check out the afk CLI tool for a ready-to-use client, or contact us at support@chatbridge.net.

Get Your API Key

Contents

Authentication

POST Send WhatsApp Message

Request Body

Example Request

Response

Response Codes

POST Send SMS Message

Request Body

Example Request

Response

Response Codes

GET Receive Responses (SSE)

Path Parameters

Event Format

Example (curl)

Webhooks (Fire & Forget)

Fire-and-Forget Pattern

CI/CD Integration Examples

GitHub Actions

GitLab CI

Jenkins Pipeline

Monitoring & Alerting

Prometheus Alertmanager

Simple Health Check Script

Batch Notifications

Rate Limits

Code Examples

Python

Node.js

Go

Shell (Bash)

Need Help?