GraphQL API#

The primary API for interacting with Outeract. GraphQL provides flexible queries and type-safe mutations.

Endpoint#

POST https://api.outeract.com/

Headers#

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Note: The X-Outeract-App-ID header is only required for JWT authentication. API keys are already scoped to a specific application.

Schema Exploration#

GraphQL Playground#

Access the interactive playground at:

https://api.outeract.com/

Introspection Query#

{
  __schema {
    types {
      name
      description
    }
  }
}

Queries#

Get Application#

query {
  application {
    id
    name
    config
    platformConnections {
      id
      platformName
      name
      status
    }
  }
}

List Events#

query Events($first: Int, $after: String, $filters: EventFilters) {
  events(first: $first, after: $after, filters: $filters) {
    edges {
      node {
        id
        eventType
        payload
        status
        createdAt
        processedAt
        edges {
          id
          edgeType
          targetNodeType
          targetPlatformUser {
            id
            externalId
            name
          }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Variables:

{
  "first": 20,
  "after": null,
  "filters": {
    "eventType": { "contains": "message" },
    "createdAt": { "gte": "2024-01-01T00:00:00Z" }
  }
}

Get Single Event#

query Event($id: UUID!) {
  event(id: $id) {
    id
    eventType
    payload
    status
    createdAt
    originEvent {
      id
      eventType
    }
    childEvents {
      id
      eventType
      createdAt
    }
    edges {
      edgeType
      targetNodeType
      targetUser {
        id
        name
      }
      targetPlatformUser {
        id
        externalId
      }
      targetFile {
        id
        filename
        mimeType
        url
      }
    }
  }
}

List Users#

query Users($first: Int, $filters: UserFilters) {
  users(first: $first, filters: $filters) {
    edges {
      node {
        id
        name
        isSystemUser
        createdAt
        platformUsers {
          id
          externalId
          platformConnection {
            id
            platformName
          }
        }
      }
    }
  }
}

List Platform Users#

query PlatformUsers($platformConnectionId: UUID, $first: Int) {
  platformUsers(
    platformConnectionId: $platformConnectionId
    first: $first
  ) {
    edges {
      node {
        id
        externalId
        name
        profilePictureUrl
        user {
          id
          name
        }
        platformConnection {
          id
          platformName
        }
      }
    }
  }
}

List Platform Connections#

query {
  platformConnections {
    id
    name
    platformName
    status
    webhookUrl
    health {
      status
      lastCheckedAt
      errorMessage
    }
    createdAt
  }
}

Get Platform Connection#

query PlatformConnection($id: UUID!) {
  platformConnection(id: $id) {
    id
    name
    platformName
    status
    config
    webhookUrl
    health {
      status
      lastCheckedAt
      errorMessage
    }
  }
}

List Files#

query Files($first: Int) {
  files(first: $first) {
    edges {
      node {
        id
        filename
        mimeType
        sizeBytes
        url
        createdAt
      }
    }
  }
}

List Event Schemas#

query {
  eventSchemas {
    id
    name
    description
    jsonSchema
    enforceValidation
    isGlobal
  }
}

Mutations#

Send Message#

mutation SendMessage(
  $platformConnectionId: UUID!
  $toExternalId: String!
  $message: String!
  $fileIds: [UUID!]
  $metadata: JSON
) {
  sendMessage(
    platformConnectionId: $platformConnectionId
    toExternalId: $toExternalId
    message: $message
    fileIds: $fileIds
    metadata: $metadata
  ) {
    id
    status {
      success
      externalMessageId
      error
    }
    event {
      id
      eventType
      payload
    }
  }
}

Variables:

{
  "platformConnectionId": "pc_abc123",
  "toExternalId": "+14155551234",
  "message": "Hello from Outeract!",
  "fileIds": ["file_xyz789"],
  "metadata": {
    "campaign_id": "camp_123"
  }
}

Create Event#

mutation CreateEvent(
  $eventType: String!
  $payload: JSON!
  $edges: [EdgeInput!]
) {
  createEvent(
    eventType: $eventType
    payload: $payload
    edges: $edges
  ) {
    id
    eventType
    payload
    createdAt
  }
}

Create Edge#

mutation CreateEdge(
  $sourceNodeId: UUID!
  $sourceNodeType: NodeType!
  $targetNodeId: UUID!
  $targetNodeType: NodeType!
  $edgeType: String!
) {
  createEdge(
    sourceNodeId: $sourceNodeId
    sourceNodeType: $sourceNodeType
    targetNodeId: $targetNodeId
    targetNodeType: $targetNodeType
    edgeType: $edgeType
  ) {
    id
    edgeType
    sourceNodeId
    targetNodeId
  }
}

Create User#

mutation CreateUser($name: String!) {
  createUser(name: $name) {
    id
    name
    createdAt
  }
}

Create Platform User#

mutation CreatePlatformUser(
  $userId: UUID!
  $platformConnectionId: UUID!
  $externalId: String!
  $name: String
) {
  createPlatformUser(
    userId: $userId
    platformConnectionId: $platformConnectionId
    externalId: $externalId
    name: $name
  ) {
    id
    externalId
    user {
      id
      name
    }
  }
}

Merge Users#

mutation MergeUsers($sourceUserId: UUID!, $targetUserId: UUID!) {
  mergeUsers(
    sourceUserId: $sourceUserId
    targetUserId: $targetUserId
  ) {
    id
    name
    platformUsers {
      id
      externalId
    }
  }
}

Create Platform Connection#

mutation CreatePlatformConnection(
  $platformName: PlatformName!
  $name: String!
  $config: JSON!
) {
  createPlatformConnection(
    platformName: $platformName
    name: $name
    config: $config
  ) {
    id
    name
    webhookUrl
  }
}

Update Platform Connection#

mutation UpdatePlatformConnection(
  $id: UUID!
  $name: String
  $config: JSON
) {
  updatePlatformConnection(
    id: $id
    name: $name
    config: $config
  ) {
    id
    name
    config
  }
}

Delete Platform Connection#

mutation DeletePlatformConnection($id: UUID!) {
  deletePlatformConnection(id: $id)
}

Test Platform Connection#

mutation TestPlatformConnection($id: UUID!) {
  testPlatformConnection(id: $id) {
    success
    message
    health {
      status
      lastCheckedAt
      errorMessage
    }
  }
}

Upload File#

mutation UploadFile($file: Upload!, $filename: String) {
  uploadFile(file: $file, filename: $filename) {
    id
    filename
    mimeType
    sizeBytes
    url
  }
}

Create Webhook Subscription#

mutation CreateWebhookSubscription(
  $name: String!
  $targetUrl: String!
  $eventPatterns: [String!]!
  $secret: String!
) {
  createWebhookSubscription(
    name: $name
    targetUrl: $targetUrl
    eventPatterns: $eventPatterns
    secret: $secret
  ) {
    id
    name
    targetUrl
    eventPatterns
  }
}

Create Event Schema#

mutation CreateEventSchema(
  $name: String!
  $description: String
  $jsonSchema: JSON!
  $enforceValidation: Boolean
) {
  createEventSchema(
    name: $name
    description: $description
    jsonSchema: $jsonSchema
    enforceValidation: $enforceValidation
  ) {
    id
    name
  }
}

Pagination#

Outeract uses cursor-based pagination following the Relay specification.

Forward Pagination#

query {
  events(first: 20, after: "cursor_xyz") {
    edges {
      node { id }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Backward Pagination#

query {
  events(last: 20, before: "cursor_xyz") {
    edges {
      node { id }
      cursor
    }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

Filtering#

String Filters#

{
  eventType: { equals: "message.inbound" }
  eventType: { contains: "message" }
  eventType: { startsWith: "custom." }
  eventType: { in: ["message.inbound", "message.outbound"] }
}

Date Filters#

{
  createdAt: { gte: "2024-01-01T00:00:00Z" }
  createdAt: { lte: "2024-01-31T23:59:59Z" }
  createdAt: {
    gte: "2024-01-01T00:00:00Z"
    lte: "2024-01-31T23:59:59Z"
  }
}

UUID Filters#

{
  id: { equals: "uuid-here" }
  id: { in: ["uuid1", "uuid2"] }
}

Edge Filters#

{
  hasEdge: {
    edgeType: "sent_by"
    targetNodeId: { equals: "pu_abc123" }
  }
}

Combining Filters#

{
  and: [
    { eventType: { contains: "message" } }
    { createdAt: { gte: "2024-01-01" } }
  ]
}

{
  or: [
    { eventType: { equals: "message.inbound" } }
    { eventType: { equals: "message.outbound" } }
  ]
}

Enums#

PlatformName#

enum PlatformName {
  WHATSAPP
  INSTAGRAM
  FACEBOOK
  TELEGRAM
  SLACK
  DISCORD
  SMS
  EMAIL
  IMESSAGE
}

NodeType#

enum NodeType {
  EVENT
  USER
  PLATFORM_USER
  FILE
}

EventStatus#

enum EventStatus {
  PENDING
  PROCESSING
  COMPLETED
  FAILED
}

Error Handling#

GraphQL errors are returned in the errors array:

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

Handle errors in your code:

const response = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables })
});

const result = await response.json();

if (result.errors) {
  for (const error of result.errors) {
    console.error(`Error: ${error.message} (${error.extensions?.code})`);
  }
}

Batching#

Combine multiple queries in one request:

query BatchQuery {
  events(first: 10) {
    edges { node { id } }
  }
  users(first: 10) {
    edges { node { id } }
  }
  platformConnections {
    id
    name
  }
}