{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Deterministically run a specific procedure on a new conversation. Calling this endpoint\nguarantees that the named procedure runs — there is no non-deterministic routing.\n\nFin's progress is delivered asynchronously via events. If the\nprocedure pauses for user input, the conversation status becomes `awaiting_user_reply` —\nsend the user's response with [`/fin/reply`](/docs/references/rest-api/api.intercom.io/fin-agent/replytofin).\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","properties":{"headers":{"type":"object","properties":{"Intercom-Version":{"$ref":"#/definitions/intercom_version","enum":["2.17"]}},"required":[],"additionalProperties":false},"path":{"type":"object","properties":{"procedure_id":{"type":"string","examples":["12345"],"description":"The ID of the procedure to run."}},"required":["procedure_id"],"additionalProperties":false},"body":{"type":"object","properties":{"conversation_id":{"type":"string","description":"Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead.","examples":["ext-123"]},"user":{"$ref":"#/definitions/fin_agent_user"},"message":{"type":"object","description":"Optional message posted to the conversation before the procedure runs. Only `body` is required.","properties":{"body":{"type":"string","description":"The body of the message.","examples":["Starting your refund request."]},"author":{"type":"string","enum":["user","agent","fin"],"description":"Accepted but has no effect. The trigger message is always posted as an operator message.","examples":["agent"]}},"required":["body"]},"conversation_metadata":{"type":"object","description":"Metadata about the conversation. Only attributes are accepted (no history).","properties":{"attributes":{"type":"object","description":"A hash of conversation attributes. Limit to 20 attributes.\n","maxProperties":20,"additionalProperties":true,"examples":[{"order_id":"98765"}]}}},"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"]}},"required":["conversation_id","user"],"examples":[{"conversation_id":"ext-123","user":{"id":"123456","name":"John Doe","email":"john.doe@example.com"}}]}},"required":["path","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_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"]}}},"name":"Run a Fin procedure","id":"intercom.runfinprocedure","example":{"path":{"procedure_id":"12345"},"body":{"conversation_id":"ext-123","user":{"id":"123456","name":"John Doe","email":"john.doe@example.com"}}},"maxRequests":1,"summary":false}}