INintercom
Fin Agent

Ask Fin

Changed on

Ask Fin a single, self-contained question and receive one informational answer.

Unlike a conversation, /fin/ask is non-conversational: Fin will not ask follow-up questions, will not run procedures, and will not escalate to a human on its own. You can still escalate one yourself with POST /fin/escalate; the ask conversation is already closed after its one-shot answer, and escalation leaves it closed while routing the handoff separately.

Fin's answer is delivered asynchronously via the fin_replied event. The conversation ends with a complete status — there is no awaiting_user_reply cycle.

{% admonition type="warning" %} To request access to the Fin Agent API, go to Settings > Integrations > Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent > Deploy. {% /admonition %}

post/fin/ask

Request

  • Base URL
    https://api.intercom.io
  • Auth
    HTTP bearer

Headers

Intercom-Version'1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14'

Intercom API version.</br>By default, it's equal to the version set in the app package.

Example:2.14

Request body

conversation_idstring required

Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use /fin/reply instead.

environmentstring

The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as messenger_environment in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.

Example request

{
  "conversation_id": "ext-123",
  "message": {
    "author": "user",
    "body": "How can I see my account details?",
    "timestamp": "2025-01-24T10:01:20.000Z",
    "timestamp_ms": "2025-01-24T10:01:20.456Z"
  },
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": {
      "plan_type": "Pro",
      "subscription_status": "active"
    }
  },
  "conversation_metadata": {
    "history": [
      {
        "author": "user",
        "body": "How can I see my account details?",
        "timestamp": "2025-01-24T10:01:20.000Z",
        "timestamp_ms": "2025-01-24T10:01:20.456Z"
      }
    ],
    "attributes": {
      "priority_level": "high",
      "department": "sales"
    }
  },
  "attachments": [
    {
      "type": "url",
      "url": "https://example.com/document.pdf",
      "name": "screenshot.png",
      "content_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."
    }
  ],
  "environment": "a1b2c3d4e5"
}

Response

Question accepted successfully

conversation_idstring

The external ID of the conversation.

intercom_conversation_idstring

The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.

user_idstring

The ID of the user.

status'thinking' | 'replying' | 'resolved' | 'complete'

Fin's current status in the conversation workflow.

created_at_msstring date-time

The timestamp the response was created at, with millisecond precision.

Example response

{
  "conversation_id": "ext-123",
  "intercom_conversation_id": "192837465",
  "user_id": "user-456",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z",
  "errors": {
    "user": {
      "attributes": {
        "invalid_attr": "User attribute 'invalid_attr' does not exist"
      }
    },
    "conversation": {
      "attributes": {
        "bad_attr": "Conversation attribute 'bad_attr' does not exist"
      }
    }
  }
}

Changes