Zeus API Quickstart

Set up Zeus API integration, send your first message and receive webhooks.

Prerequisites

• Zeus account
• Publicly accessible webhook endpoint
• API token and webhook secret from Zeus Settings

1. Get your credentials

   Go to Dashboard → Configuration → API and copy your API token and Webhook secret.

2. Create a webhook endpoint (choose one)

   Python (Flask)

   server.py

   import hashlib
   import hmac
   import json
   from flask import Flask, request, jsonify
   
   app = Flask(__name__)
   
   WEBHOOK_SECRET = "your_webhook_secret_here"
   
   # helper method to verify if webhook is from Zeus
   def verify_signature(payload, signature, timestamp, secret):
       signed_payload = f"{timestamp}.{payload}"
       expected_signature = hmac.new(
           secret.encode('ascii'),
           signed_payload.encode('utf-8'),
           hashlib.sha256
       ).hexdigest()
       return hmac.compare_digest(signature, expected_signature)
   
   @app.route('/webhook', methods=['POST'])
   def handle_webhook():
       payload = request.get_data(as_text=True)
       signature = request.headers.get('X-Zeus-Webhook-Signature')
       timestamp = request.headers.get('X-Zeus-Webhook-Timestamp')
   
       if not verify_signature(payload, signature, timestamp, WEBHOOK_SECRET):
           return jsonify({'error': 'Invalid signature'}), 401
   
       event = json.loads(payload)
       if event['event'] == 'send_messages':
           for message in event['data']['messages']:
               print(f"AI Response: {message['text']}")
       return jsonify({'status': 'received'})
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=5000)
   

   Node.js (Express)

   server.js

   const express = require("express");
   const crypto = require("crypto");
   const app = express();
   
   const WEBHOOK_SECRET = "your_webhook_secret_here";
   
   app.use(express.raw({ type: "application/json" }));
   
   // helper method to verify if webhook is from Zeus
   function verifySignature(payload, signature, timestamp, secret) {
     const signedPayload = `${timestamp}.${payload}`;
     const expectedSignature = crypto
       .createHmac("sha256", secret)
       .update(signedPayload, "utf8")
       .digest("hex");
     return crypto.timingSafeEqual(
       Buffer.from(signature, "hex"),
       Buffer.from(expectedSignature, "hex")
     );
   }
   
   app.post("/webhook", (req, res) => {
     const payload = req.body.toString();
     const signature = req.headers["x-zeus-webhook-signature"];
     const timestamp = req.headers["x-zeus-webhook-timestamp"];
   
     if (!verifySignature(payload, signature, timestamp, WEBHOOK_SECRET)) {
       return res.status(401).json({ error: "Invalid signature" });
     }
   
     const event = JSON.parse(payload);
     if (event.event === "send_messages") {
       event.data.messages.forEach((m) => console.log(`AI Response: ${m.text}`));
     }
     res.json({ status: "received" });
   });
   
   app.listen(5000, () => console.log("Webhook server on 5000"));
   
3. Create API integration

   Contact Atlas team to setup API integration. Provide them with your public webhook URL, any custom headers, and metadata you want to receive with each webhook.

   You should receive an integration ID. Use this ID in API requests.

4. Send first message

   Head over to Message Received API to send your first message.

   cURL

   curl -X POST https://zeus-api.atlas.so/v1/webhooks/{integration_id}/message-received \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "msg_1",
       "role": "human",
       "sent_at": "2024-01-15T10:30:00Z",
       "customer_id": "CUSTOMER_ID",
       "text": "Hello, I need help",
       "conversation_id": "conv_1"
     }'
   

   You should receive a send_messages webhook with Zeus AI’s reply.

Use the same conversation_id to keep messages threaded. Set sync_only: true to import history without triggering AI responses.