API Reference#

Outeract provides a GraphQL API for managing your messaging infrastructure.

API Endpoints#

Authentication#

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Note: API keys are scoped to a specific application, so the X-Outeract-App-ID header is not required.

Quick Reference#

Common Headers#

Rate Limits#

Rate limits are set per API key. Each key defaults to 100 requests/minute and can be configured with a custom rateLimitPerMinute (up to 1,000) when the key is created or updated.

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1699574400

See Rate Limits for details.

API Sections#

GraphQL API#

Primary API for all operations:

• Schema exploration
• Queries and mutations
• Pagination patterns
• Error handling

Webhooks#

Receive real-time events:

• Inbound messages
• Delivery status
• Signature verification
• Retry policies

Outbound Webhooks#

Subscribe to events:

• Event patterns
• Payload format
• Managing subscriptions
• Debugging

Code Examples#

Send a Message#

mutation SendMessage {
  sendMessage(
    recipientUserId: "123e4567-e89b-12d3-a456-426614174000"
    message: "Hello from Outeract!"
  ) {
    id
    eventTypeName
    payload
    createdAt
  }
}

Query Events#

query RecentEvents {
  events(
    eventTypes: ["message.inbound", "message.outbound"]
    first: 20
  ) {
    edges {
      node {
        id
        eventTypeName
        payload
        createdAt
        edges {
          edgeType
          targetNodeType
          targetNodeId
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Create a Log#

mutation CreateLog {
  createLog(
    message: "Processing started for user request"
    logLevel: "info"
    logType: "execution"
    payload: {step: "initialization", duration_ms: 42}
    eventId: "123e4567-e89b-12d3-a456-426614174000"
  ) {
    id
    createdAt
    message
    logLevel
  }
}

Error Handling#

GraphQL Errors#

{
  "data": null,
  "errors": [
    {
      "message": "Platform connection not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["sendMessage"],
      "extensions": {
        "code": "NOT_FOUND",
        "http": {"status": 404}
      }
    }
  ]
}

Error Codes#

SDKs and Libraries#

Official SDKs#

Coming soon:

• Python SDK
• Node.js SDK
• Go SDK

Community Libraries#

Check our GitHub for community-contributed libraries.

Testing#

Test Applications#

Create a separate application for development. Applications fully isolate users, events, and platform connections. Connect a test bot or number (e.g., your own Telegram bot) so you can send real messages without touching production data. Every account gets a $10 free usage credit each month, which comfortably covers development traffic.

Webhook Testing#

Use tools like webhook.site or ngrok for local development.