API Reference

Complete reference for all API methods available for your chat bot.

Sending Messages

POST /bot/send-message

This is the primary method for your bot to send messages to users.

Headers:

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

Request Body:

{
  "uid": 12345,
  "message": {
    "text": "Hello! How can I help you today?",
    "buttonMarkup": [
      [
        { "text": "Get Started", "callbackData": "start_action" },
        { "text": "Help", "url": "https://example.com/help" }
      ]
    ]
  }
}

Parameters:

Field	Type	Required	Description
uid	number	Yes	The user's unique identifier
message	object	Yes	The message object
message.text	string	No	The text content of the message
message.buttonMarkup	array	No	An array of button rows (see Interactive Buttons)
message.media	array	No	An array of media attachments (e.g., images)

Response:

A successful request will return a JSON object with the ID of the sent message:

{
  "success": true,
  "messageId": "507f1f77bcf86cd799439011"
}

Examples:

Simple Text Message:

async function sendWelcomeMessage(userId) {
  try {
    const response = await bot.sendMessage(userId, {
      text: 'Welcome to our service! 🎉',
    });
    console.log('Message sent:', response);
  } catch (error) {
    console.error('Failed to send message:', error);
  }
}

sendWelcomeMessage(12345);

Message with Interactive Buttons:

async function sendMenuMessage(userId) {
  const message = {
    text: 'What would you like to do?',
    buttonMarkup: [
      [
        { text: '📋 View Products', callbackData: 'menu_products' },
        { text: '🛒 My Orders', callbackData: 'menu_orders' },
      ],
      [{ text: '🌐 Visit Website', url: 'https://example.com' }],
    ],
  };

  try {
    const response = await bot.sendMessage(userId, message);
    console.log('Menu sent:', response);
  } catch (error) {
    console.error('Failed to send menu:', error);
  }
}

sendMenuMessage(12345);

Interactive Buttons

Add interactive buttons to your messages to create engaging, menu-driven experiences. Buttons are organized in rows within the buttonMarkup array.

Button Structure

Each button is an object with a text property and one of callbackData, url, or copyText:

{
  "text": "Button Label",
  "url": "https://example.com",        // Optional: For URL buttons
  "callbackData": "custom_data",       // Optional: For callback buttons
  "copyText": "text to copy"           // Optional: For copy buttons
}

Button Types

1. Callback Button

Triggers a callback-query webhook event when clicked. This is the primary way to handle interactive actions within your bot.

Structure: { "text": "Get Started", "callbackData": "start_action" }

Use Cases: Menu navigation, triggering bot actions, confirming choices.

2. URL Button

Opens a web page in the user's browser when clicked.

Structure: { "text": "Visit Website", "url": "https://example.com" }

Use Cases: Linking to your website, documentation, or payment pages.

3. Copy Button

Copies a specified string of text to the user's clipboard when clicked.

Structure: { "text": "Copy Code", "copyText": "PROMO2024" }

Use Cases: Sharing promo codes, referral links, or wallet addresses.

Button Layout

Buttons are arranged in an array of arrays, where each inner array represents a row of buttons:

"buttonMarkup": [
  [ button1, button2 ],    // First row with 2 buttons
  [ button3 ],             // Second row with 1 button
]

Button Examples

E-commerce Menu:

"buttonMarkup": [
  [
    { "text": "🛍️ Browse Products", "callbackData": "menu_products" },
    { "text": "🛒 My Cart", "callbackData": "menu_cart" }
  ],
  [
    { "text": "📞 Contact Support", "callbackData": "menu_support" },
    { "text": "🌐 Visit Store", "url": "https://store.example.com" }
  ]
]

Promotional Message:

"buttonMarkup": [
  [
    { "text": "📋 Copy Code", "copyText": "SAVE20" },
    { "text": "🛒 Shop Now", "url": "https://store.example.com/promo" }
  ],
  [
    { "text": "❌ No Thanks", "callbackData": "promo_decline" }
  ]
]

Limitations

• Max buttons per message: 10
• Max buttons per row: 4
• Button text length: 20 characters
• Callback data length: 64 characters
• URL length: 2048 characters
• Copy text length: 256 characters