Skip to main content
POST
/
v2
/
hc-interactions
/
events
/
public
curl --request POST \
  --url 'https://api-prod.usefini.com/v2/hc-interactions/events/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
    "role": "user",
    "content": "Where is my order?",
    "metadata": {
      "user_attributes": {
        "email": "customer@example.com"
      },
      "channel": "chat"
    }
  }'

[
  {
    "id": "cc0e1592-4b71-4f57-bf9c-1b10a6b7b71a",
    "createdAt": 1749640953000,
    "role": "user",
    "type": "message",
    "message": "Where is my order?",
    "externalId": null,
    "externalCreatedAt": null,
    "csatRating": null,
    "feedback": null,
    "approved": null,
    "resolved": null,
    "attachments": [],
    "tags": [],
    "usedArticles": []
  },
  {
    "id": "da370d54-5d2a-4b38-b99d-8b5c5f77bff7",
    "createdAt": 1749640955000,
    "role": "finibot",
    "type": "message",
    "message": "I can help with that. What is your order number?",
    "externalId": null,
    "externalCreatedAt": null,
    "csatRating": null,
    "feedback": null,
    "approved": null,
    "resolved": null,
    "attachments": [],
    "tags": [],
    "usedArticles": [
      {
        "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
        "title": "Track your order",
        "documentUrl": null
      }
    ]
  }
]
Use this endpoint when your backend needs to send a turn into Fini. Pass interactionId to continue an existing conversation, or botId to let Fini create or resolve one for that agent. The route stores the incoming event, runs the normal reply flow for user messages, and returns the public event objects created while handling that submission.
Use List agents to get a botId. This route returns only the created event array, not the full conversation wrapper. Use Get conversation when you already know the conversation ID, or List conversations when you need to discover or export it.

​
Headers

​
Authorization
string
required
Bearer token containing your Fini workspace API key. Format: Bearer fini_... The key needs write scope.

​
Body parameters

​
content
string
required
Message text to add as the incoming event.
​
role
string
default:"user"
Event role. Allowed values are user, agent, finibot, and otherbot. Most public callers should use user.
​
interactionId
string
Existing conversation ID to continue. If omitted, provide botId and Fini will create or resolve a conversation for that bot.
​
botId
string
Agent ID to use when starting a new conversation. Required when interactionId is omitted.
​
metadata
object
Optional conversation metadata to merge into the request state.
Public attachment upload support for Generate Answer is coming soon through a dedicated public API flow. Until that ships, treat this route as text-only.

​
Request example

curl --request POST \
  --url 'https://api-prod.usefini.com/v2/hc-interactions/events/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
    "role": "user",
    "content": "Where is my order?",
    "metadata": {
      "user_attributes": {
        "email": "customer@example.com"
      },
      "channel": "chat"
    }
  }'
If you send role: "agent" or another non-user role, Fini stores that event and returns it immediately. The route only generates a new AI reply for user events.

​
Response

The response is a top-level array of public events created while handling this submission. This is the same event shape returned inside events[] on List conversations.
​
[]
array
Array of public events created for the submission.
[
  {
    "id": "cc0e1592-4b71-4f57-bf9c-1b10a6b7b71a",
    "createdAt": 1749640953000,
    "role": "user",
    "type": "message",
    "message": "Where is my order?",
    "externalId": null,
    "externalCreatedAt": null,
    "csatRating": null,
    "feedback": null,
    "approved": null,
    "resolved": null,
    "attachments": [],
    "tags": [],
    "usedArticles": []
  },
  {
    "id": "da370d54-5d2a-4b38-b99d-8b5c5f77bff7",
    "createdAt": 1749640955000,
    "role": "finibot",
    "type": "message",
    "message": "I can help with that. What is your order number?",
    "externalId": null,
    "externalCreatedAt": null,
    "csatRating": null,
    "feedback": null,
    "approved": null,
    "resolved": null,
    "attachments": [],
    "tags": [],
    "usedArticles": [
      {
        "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
        "title": "Track your order",
        "documentUrl": null
      }
    ]
  }
]

​
Errors

The body is malformed. Common causes are omitting content, or omitting both interactionId and botId.
The API key is missing, malformed, revoked, or invalid. Confirm you are sending Authorization: Bearer fini_... with the full key.
The API key does not include the write scope required for this route.
Fini failed while resolving the bot, loading or creating the conversation, persisting the event, or generating the reply. Unknown interactionId or botId values currently surface here on the public route as well. Retry once, then investigate the conversation in Inbox if the error persists.