INintercom
Fin Agent

Reply to Fin

Changed on

Once Fin has returned a response to a user's message, its status will be awaiting_user_reply.

If a user replies, use this endpoint to send this response to Fin.

{% 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/reply

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

The ID of the conversation.

Example request

{
  "conversation_id": "123456",
  "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"
    }
  },
  "attachments": [
    {
      "type": "url",
      "url": "https://example.com/document.pdf",
      "name": "screenshot.png",
      "content_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."
    }
  ]
}

Response

Reply sent successfully

conversation_idstring

The 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' | 'awaiting_user_reply' | 'escalated' | '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