Sociogram Docs

Appearance

Webhooks: Receiving Events ​

Webhooks are the way your bot receives information about user interactions. The Sociogram Bot API allows your bot to listen for specific events sent from the Sociogram platform.

How Webhooks Work ​

  1. User interacts with bot: A user sends a message or clicks a button in your bot
  2. Platform processes interaction: The Sociogram platform receives the user's action
  3. Platform sends webhook: The platform sends a POST request with JSON payload to your webhook URL
  4. Bot processes webhook: Your server receives the webhook and can respond by sending a message

Webhook URL Setup ​

When you register your bot in the Developer Portal, you must provide a webhook URL. Sociogram will send POST requests with a JSON body to this URL for every event.

Webhook Verification ​

All webhook requests sent from Sociogram to your server will include your bot's token in the X-App-Key header. You must verify this token to ensure the request is authentic:

javascript
{
  'X-App-Key': 'your-bot-token',
  'Content-Type': 'application/json'
}

Webhook Event Structure ​

All webhook events follow a common structure, with the specific event data nested inside the data object:

javascript
{
  "data": {
    // Event-specific object will be here
    // e.g., "chat-message": { ... }
  }
}

Webhook Event Types ​

chat-message: User Sends a Message ​

This event is sent when a user sends a text message to your bot.

Payload:

javascript
{
  "data": {
    "chat-message": {
      "uid": 12345,
      "chatId": "507f1f77bcf86cd799439011",
      "message": {
        "text": "Hello bot!"
      }
    }
  }
}

callback-query: User Clicks a Button ​

This event is sent when a user clicks a Callback Button in one of your messages. This payload includes the uid so you know which user to respond to.

Payload:

javascript
{
  "data": {
    "callback-query": {
      "uid": 12345,
      "chatId": "507f1f77bcf86cd799439011",
      "callbackData": "menu_products"
    }
  }
}

Handling Webhook Events ​

Here is a complete example of handler functions for your webhook server:

javascript
// handlers.js
const { bot } = require('./bot-client');

async function handleUserMessage(data) {
  const { uid, message } = data;

  // Simple echo bot logic
  if (message.text && message.text.toLowerCase().includes('hello')) {
    await bot.sendMessage(uid, {
      text: `Hello there! You said: "${message.text}"`,
      buttonMarkup: [[{ text: 'Tell me more', callbackData: 'more_info' }]],
    });
  }
}

async function handleButtonClick(data) {
  const { uid, callbackData } = data;

  switch (callbackData) {
    case 'greeting':
      await bot.sendMessage(uid, {
        text: "Great to meet you! I'm here to help.",
      });
      break;

    case 'menu_products':
      await bot.sendMessage(uid, {
        text: 'Here are our products: Product A, Product B, Product C.',
      });
      break;

    case 'menu_support':
      await bot.sendMessage(uid, {
        text: 'How can I help you?',
        buttonMarkup: [
          [{ text: '📖 Documentation', url: 'https://docs.example.com' }],
          [{ text: '💬 Live Chat', callbackData: 'support_live_chat' }],
        ],
      });
      break;

    default:
      await bot.sendMessage(uid, {
        text: `You clicked a button with data: ${callbackData}`,
      });
      break;
  }
}

module.exports = { handleUserMessage, handleButtonClick };