Sociogram Docs

Appearance

Getting Started ​

Welcome to the Sociogram Bot API! This guide will help you get started with building automated applications that can send and receive messages, present interactive buttons, and react to user actions within Sociogram.

Core Concepts ​

The Sociogram Bot API facilitates a two-way communication channel between your bot and the Sociogram platform.

  1. Bot Server: Your backend server that makes authenticated API calls to send messages to users and receives webhook events when users interact with your bot.

  2. Sociogram Platform: The main Sociogram application that delivers messages to users and sends webhook events to your bot when users interact.

  3. Interaction Loop: The core interaction model is based on a simple, powerful loop:

    • Send Messages: Your backend server makes authenticated API calls to send content to users
    • Receive Webhooks: When users interact with your bot, Sociogram sends JSON payloads to your webhook URL
    • Process and Respond: Your server processes the webhook data and can respond by sending another message

API Base URL ​

All API requests should be sent to:

https://api.sociogram.org

Authentication ​

All API requests from your server to the Sociogram API must be authenticated using your unique bot token. The token must be included in the X-App-Key HTTP header.

X-App-Key: your-bot-token-here

Similarly, all webhook requests from Sociogram to your server will include this header, allowing you to verify that the request is legitimate.

Rate Limits ​

To ensure platform stability, the following rate limits apply:

  • Message Sending: 60 messages per minute per bot
  • User-Specific: 1 message per second to a single user

Step 1: Create Your Bot & Get a Token ​

  1. Go to the Sociogram Developer Portal
  2. Click "Create New Bot" and fill in the required information
  3. Provide a Webhook URL (see Step 3)
  4. After creation, you will receive a Bot Token

Step 2: Backend Setup & API Client ​

We recommend creating a simple API client class to manage requests and authentication:

javascript
class SociogramBot {
  constructor(token, baseUrl = 'https://api.sociogram.org') {
    this.token = token;
    this.baseUrl = baseUrl;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Content-Type': 'application/json',
      'X-App-Key': this.token,
      ...options.headers,
    };

    const config = {
      ...options,
      headers,
    };

    const response = await fetch(url, config);
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`HTTP ${response.status}: ${errorText}`);
    }

    return response.json();
  }

  async sendMessage(uid, message) {
    return this.request('/bot/send-message', {
      method: 'POST',
      body: JSON.stringify({ uid, message }),
    });
  }
}

// Initialize your bot
const BOT_TOKEN = 'your-bot-token-here';
const bot = new SociogramBot(BOT_TOKEN);

Step 3: Set Up Your Webhook Server ​

Create a simple web server to listen for incoming webhooks from Sociogram:

javascript
const express = require('express');
const { bot, BOT_TOKEN } = require('./bot-client');

const app = express();
app.use(express.json());

// Middleware to verify webhook authenticity
function verifyWebhook(req, res, next) {
  const token = req.headers['x-app-key'];
  if (token !== BOT_TOKEN) {
    console.warn('Unauthorized webhook received');
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
}

// Webhook handler endpoint
app.post('/webhook', verifyWebhook, (req, res) => {
  console.log('Received webhook:', JSON.stringify(req.body, null, 2));

  const { data } = req.body;
  if (data['chat-message']) {
    handleUserMessage(data['chat-message']);
  } else if (data['callback-query']) {
    handleButtonClick(data['callback-query']);
  }

  res.status(200).json({ success: true });
});

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

Next Steps ​