Sign in

v3

latestOpenAPI 3.0.02026-08-081996601.2 MB
Agent Connectors

Create agent connector

Creates a connector for an agent to receive events from an external platform such as Slack, Google Chat, or Zoom Contact Center.

post/v2/agents/{agent_key}/connectors

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique identifier of the agent to create a connector for.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

namestring required

The human-readable name of the connector.

descriptionstring

A detailed description of what this connector does.

metadataobject

Arbitrary metadata associated with the connector.

enabledboolean

Whether the connector should be enabled upon creation.

Example request

{
  "name": "Customer Support Slack Channel",
  "description": "Receives customer support messages from the",
  "metadata": {
    "priority": "high",
    "department": "customer_service"
  },
  "enabled": true,
  "configuration": {
    "hidden_output_types": [
      "tool_calls"
    ],
    "type": "slack",
    "bot_token": "xoxb-1234567890-1234567890123-abcdefghijklmnopqrstuvwx",
    "signing_secret": "abcdef1234567890abcdef1234567890abcdef12",
    "api_app_id": "A1234567890"
  }
}

Response

The created connector.

idstring required

The unique identifier for the connector.

agent_keystring required

A unique key that identifies an agent.

namestring required

The human-readable name of the connector.

descriptionstring

A detailed description of what this connector does.

type'slack' | 'gchat' | 'zoom' required

The type of connector.

status'active' | 'inactive' | 'error' required

The current status of the connector.

status_messagestring

Detailed status message (e.g., error description or success confirmation).

metadataobject

Arbitrary metadata associated with the connector.

enabledboolean required

Whether the connector is currently enabled and can receive events.

created_atstring date-time required

Timestamp when the connector was created.

updated_atstring date-time

Timestamp when the connector was last updated.

last_webhook_atstring date-time

Timestamp of the most recently received inbound webhook for this connector, regardless of outcome. Absent until the first webhook arrives.

last_webhook_status'success' | 'jwt_verification_failed' | 'audience_mismatch' | 'auth_failed' | 'missing_signature' | 'missing_engagement' | 'event_parse_failed' | 'internal_error' | 'unknown'

Outcome of the most recently received inbound webhook. Absent until the first webhook arrives. Values:

  • success: the webhook verified and the event was accepted.
  • jwt_verification_failed: the bearer token was missing or could not be verified.
  • audience_mismatch: the token was valid but its aud did not equal the connector's audience_url.
  • auth_failed: the inbound request lacked or did not match the connector's authentication secret.
  • missing_signature: the request lacked the signature needed for an asynchronous reply.
  • missing_engagement: the request lacked the engagement identifier needed to route the session.
  • event_parse_failed: the event body could not be parsed.
  • internal_error: an unexpected error occurred after the connector was resolved.
  • unknown: the outcome could not be classified.

Example response

{
  "id": "con_3Kx9QpVn2mZr8YbLc5TdWe",
  "agent_key": "customer_support",
  "name": "Customer Support Slack Channel",
  "description": "Receives customer support messages from the",
  "type": "slack",
  "status": "active",
  "status_message": "Slack authentication successful",
  "metadata": {
    "priority": "high",
    "department": "customer_service"
  },
  "enabled": true,
  "configuration": {
    "hidden_output_types": [
      "tool_calls"
    ],
    "type": "slack",
    "bot_token": "xoxb-1234567890-1234567890123-abcdefghijklmnopqrstuvwx",
    "signing_secret": "abcdef1234567890abcdef1234567890abcdef12",
    "api_app_id": "A1234567890",
    "webhook_path": "/v2/agents/customer_support/connectors/con_3Kx9QpVn2mZr8YbLc5TdWe/input"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T14:45:00Z",
  "last_webhook_at": "2024-01-16T14:45:00Z",
  "last_webhook_status": "success"
}