Sign in
Agent Connectors

Create agent connector

Creates a connector on an alias to receive events from an external platform such as Slack, Google Chat, or Zoom Contact Center, or to serve the embeddable widget. Sessions created through the connector are routed to an agent by the alias's policy.

post/v2/agent_aliases/{alias_key}/connectors

Path parameters

alias_keystring required

The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to /v2/agent_aliases/{key}/... target the alias. Calls to /v2/agents/{key}/... target the agent.

Example:support

The unique key of the alias to create a connector on.

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.

type'slack' | 'gchat' | 'zoom' | 'widget'

Optional confirmation of the connector type. When supplied it must match configuration.type; when omitted the type is taken from configuration.type.

Example request

{
  "name": "Customer Support Slack Channel",
  "description": "Receives customer support messages from the",
  "metadata": {
    "priority": "high",
    "department": "customer_service"
  },
  "enabled": true,
  "type": "slack",
  "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 globally unique identifier of a connector.

alias_keystring required

The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to /v2/agent_aliases/{key}/... target the alias. Calls to /v2/agents/{key}/... target the agent.

namestring required

The human-readable name of the connector.

descriptionstring

A detailed description of what this connector does.

type'slack' | 'gchat' | 'zoom' | 'widget' 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_support_9f3a1c2b4d5e6f708192a3b4c5d6e7f8",
  "alias_key": "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"
}

Changes