{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Initialize Fin by passing it the user's message along with conversation history and user details.\n\nThese additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.\n\n{% admonition type=\"warning\" %}\nTo 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**.\n{% /admonition %}\n\nOnce Fin is initialized, it progresses through a series of statuses such as *thinking*, *replying*, *awaiting_user_reply*, or *resolved* before ending with a status of *complete*.\n\nDuring this workflow, the client should allow Fin to continue uninterrupted until a final *complete* status is returned via webhook, at which point control of the conversation passes back to the client.\n","properties":{"headers":{"type":"object","properties":{"Intercom-Version":{"$ref":"#/definitions/intercom_version","enum":["2.17"]}},"required":[],"additionalProperties":false},"body":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The ID of the conversation that is calling Fin via this API.","examples":["ext-123"]},"message":{"$ref":"#/definitions/fin_agent_message"},"user":{"$ref":"#/definitions/fin_agent_user"},"attachments":{"type":"array","description":"An array of attachments to include with the message. Maximum of 10 attachments.","maxItems":10,"items":{"$ref":"#/definitions/fin_agent_attachment"}},"conversation_metadata":{"$ref":"#/definitions/fin_agent_conversation_metadata"},"environment":{"type":"string","description":"The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error.","examples":["a1b2c3d4e5"]},"response_format":{"type":"string","enum":["html","markdown"],"default":"html","description":"The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error.","examples":["html"]}},"required":["conversation_id","message","user"],"examples":[{"conversation_id":"ext-123","message":{"author":"user","body":"How can I see my account details?","timestamp":"2025-01-24T10:01:20.000Z"},"user":{"id":"123456","name":"John Doe","email":"john.doe@example.com"}}]}},"required":["body"],"additionalProperties":false,"definitions":{"intercom_version":{"description":"Intercom API version.</br>If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.","type":"string","enum":["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","2.15","2.16","2.17"],"examples":["2.17"]},"fin_agent_message":{"title":"Fin Agent Message","type":"object","description":"A message exchanged within a Fin Agent conversation.","properties":{"author":{"type":"string","enum":["user","agent","fin"],"description":"The author that created the message. In `conversation_metadata.history`, only `user` and `agent` are accepted.","examples":["user"]},"body":{"type":"string","description":"The body of the message. Accepts both plain text and HTML format.\nFor the message you send to Fin, this is the user's message. For an `agent` item in `conversation_metadata.history`, it is the agent's message.\nFin's response is returned in the format set by `response_format` (HTML by default).\n","examples":["How can I see my account details?"]},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the message was created.\nUsed to deduplicate messages sent within a 5 minute window.\nIdeally should include milliseconds for higher precision.\nSend `timestamp` or `timestamp_ms`; at least one is required. If you send both, `timestamp_ms` is used.\nOn the top-level `message`, sending neither fails with a 422 error (`message: timestamp_ms is required`). In `conversation_metadata.history`, an item with neither causes the whole history to be ignored.\n","examples":["2025-01-24T10:01:20.000Z"]},"timestamp_ms":{"type":"string","format":"date-time","description":"The timestamp when the message was created, with millisecond precision.\nAccepted in place of `timestamp` when you send a message, and also present in webhook event responses (fin_replied). At least one of `timestamp` or `timestamp_ms` is required.\n","examples":["2025-01-24T10:01:20.456Z"]}},"required":["author","body"]},"fin_agent_user":{"title":"Fin Agent User","type":"object","description":"A user object representing the user in a Fin Agent conversation.","properties":{"id":{"type":"string","description":"The ID of the user. This value will be used to uniquely identify the user\nduring a conversation with Fin. Maps to the user_id field on the Intercom User object.\n","examples":["123456"]},"name":{"type":"string","description":"The name of the user.","examples":["John Doe"]},"email":{"type":"string","format":"email","description":"The email of the user.","examples":["john.doe@example.com"]},"attributes":{"type":"object","description":"A hash of attributes associated with the user.\nAttributes can be used by Fin to target content and responses.\nLimit to 10 attributes.\n","additionalProperties":true,"examples":[{"plan_type":"Pro","subscription_status":"active"}]}},"required":["id"]},"fin_agent_attachment":{"title":"Fin Agent Attachment","type":"object","description":"An attachment object representing a file or URL attachment included with a message.\nAttachments can be used to provide additional context to Fin.\nMaximum of 10 attachments per request.\n","properties":{"type":{"type":"string","enum":["url","file"],"description":"The type of attachment.","examples":["url"]},"url":{"type":"string","format":"uri","description":"The URL of the attachment. Required when type is 'url'. Must be publicly accessible.","examples":["https://example.com/document.pdf"]},"name":{"type":"string","description":"The name of the file. Required when type is 'file'.","examples":["screenshot.png"]},"content_type":{"type":"string","description":"The MIME type of the file. Required when type is 'file'.","examples":["image/png"]},"data":{"type":"string","format":"byte","description":"Base64-encoded file data. Required when type is 'file'.","examples":["iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."]}},"required":["type"]},"fin_agent_conversation_metadata":{"title":"Fin Agent Conversation Metadata","type":"object","description":"Metadata about the conversation, including history and attributes.","properties":{"history":{"type":"array","description":"An array of previous messages in the conversation before Fin is initialized.\nThis data provides context to Fin and helps generate a better answer.\nLimit to the last 10 messages.\nOnly `user` and `agent` authors are accepted. If any item is invalid, for example it has no `timestamp` or `timestamp_ms`, or has another author, the whole history is ignored.\n","maxItems":10,"items":{"$ref":"#/definitions/fin_agent_message"}},"attributes":{"type":"object","description":"A hash of attributes associated with the conversation.\nThese attributes can be used by Fin to provide more contextual responses.\nLimit to 20 attributes.\n","maxProperties":20,"additionalProperties":true,"examples":[{"priority_level":"high","department":"sales"}]}}}}},"name":"Start a conversation with Fin","id":"intercom.startfinconversation","example":{"body":{"conversation_id":"ext-123","message":{"author":"user","body":"How can I see my account details?","timestamp":"2025-01-24T10:01:20.000Z"},"user":{"id":"123456","name":"John Doe","email":"john.doe@example.com"}}},"maxRequests":1,"summary":false}}