Quick Start Guide#

Get Outeract running in your application in under 5 minutes.

TL;DR#

# 1. Set your credentials
export OUTERACT_API_KEY="your-api-key"
export OUTERACT_APP_ID="your-app-id"
export OUTERACT_CONNECTION_ID="your-connection-id"

# 2. Send a message
curl -X POST https://api.outeract.com/v1/messages \
  -H "Authorization: Bearer $OUTERACT_API_KEY" \
  -H "X-Outeract-App-ID: $OUTERACT_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_connection_id": "'$OUTERACT_CONNECTION_ID'",
    "to_external_id": "+1234567890",
    "message": "Hello from Outeract!"
  }'

Step-by-Step#

Go to console.outeract.com and create an account
Create a new application - this is your messaging container
Copy your Application ID from the dashboard

2. Create an API Key#

Navigate to Settings → API Keys
Click Create API Key
Select scopes:
- events:read - For reading messages
- events:write - For sending messages
- users:read - For user lookups
- users:write - For user management
Save your API key - it’s only shown once

3. Connect a Platform#

Choose your messaging platform and follow the setup:

Platform	Auth Type	Setup Time
WhatsApp	OAuth	5 min
Instagram	OAuth	5 min
Telegram	Bot Token	2 min
Slack	Bot Token	3 min
Discord	Bot Token	3 min
SMS	API Key	2 min
Email	API Key	2 min

After connecting, copy your Platform Connection ID.

4. Send Your First Message#

REST API

curl -X POST https://api.outeract.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_connection_id": "YOUR_CONNECTION_ID",
    "to_external_id": "+1234567890",
    "message": "Hello from Outeract!"
  }'

Response:

{
  "id": "evt_abc123",
  "status": "sent",
  "external_message_id": "wamid.xxx",
  "created_at": "2024-01-15T10:30:00Z"
}

GraphQL

mutation SendMessage {
  sendMessage(
    platformConnectionId: "YOUR_CONNECTION_ID"
    toExternalId: "+1234567890"
    message: "Hello from Outeract!"
  ) {
    id
    status {
      success
      message
      externalMessageId
    }
  }
}

Headers:

Authorization: Bearer YOUR_API_KEY

5. Receive Messages (Optional)#

Set up a webhook to receive incoming messages:

curl -X POST https://api.outeract.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "target_url": "https://your-server.com/webhooks/outeract",
    "event_patterns": ["message.inbound"]
  }'

Your server will receive POST requests like:

{
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "whatsapp",
    "external_message_id": "wamid.xxx"
  },
  "edges": {
    "sent_by": {
      "id": "usr_abc123",
      "external_id": "+1234567890"
    }
  }
}

Example: Echo Bot#

Here’s a complete example that echoes messages back:

Python (Flask)

from flask import Flask, request, jsonify
import requests
import hmac
import hashlib

app = Flask(__name__)

OUTERACT_API_KEY = "your-api-key"
OUTERACT_APP_ID = "your-app-id"
WEBHOOK_SECRET = "your-webhook-secret"

@app.route("/webhooks/outeract", methods=["POST"])
def handle_webhook():
    # Verify signature
    signature = request.headers.get("X-Outeract-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(f"sha256={expected}", signature):
        return jsonify({"error": "Invalid signature"}), 401

    data = request.json

    if data["event_type"] == "message.inbound":
        # Echo the message back
        sender = data["edges"]["sent_by"]
        message_text = data["payload"]["message"]["text"]

        requests.post(
            "https://api.outeract.com/v1/messages",
            headers={
                "Authorization": f"Bearer {OUTERACT_API_KEY}",
                "X-Outeract-App-ID": OUTERACT_APP_ID,
                "Content-Type": "application/json"
            },
            json={
                "platform_connection_id": data["platform_connection_id"],
                "to_external_id": sender["external_id"],
                "message": f"You said: {message_text}"
            }
        )

    return jsonify({"status": "ok"})

if __name__ == "__main__":
    app.run(port=3000)

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

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

const OUTERACT_API_KEY = 'your-api-key';
const OUTERACT_APP_ID = 'your-app-id';
const WEBHOOK_SECRET = 'your-webhook-secret';

app.post('/webhooks/outeract', async (req, res) => {
  // Verify signature
  const signature = req.headers['x-outeract-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event_type, payload, edges, platform_connection_id } = req.body;

  if (event_type === 'message.inbound') {
    // Echo the message back
    const sender = edges.sent_by;
    const messageText = payload.message.text;

    await fetch('https://api.outeract.com/v1/messages', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${OUTERACT_API_KEY}`,
        'X-Outeract-App-ID': OUTERACT_APP_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        platform_connection_id,
        to_external_id: sender.external_id,
        message: `You said: ${messageText}`
      })
    });
  }

  res.json({ status: 'ok' });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Next Steps#

Authentication Deep Dive - Understand all auth methods
Core Concepts - Learn the data model
API Reference - Complete API documentation
Platform Guides - Detailed platform setup

Common Issues#

“Unauthorized” Error#

Check your API key is correct
Verify the X-Outeract-App-ID header is set
Ensure your API key has the required scopes

“Platform Connection Not Found”#

Verify the platform_connection_id is correct
Check the connection is active in the console

Messages Not Delivering#

For WhatsApp: Ensure the recipient has messaged you first (24-hour window)
For Telegram: Bot must be started by the user first
Check the platform connection health in the console

More troubleshooting →