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": "[email protected]"
},
"channel": "chat"
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
]
}
}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={
"botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"role": "user",
"content": "Where is my order?",
"metadata": {
"user_attributes": {"email": "[email protected]"},
"channel": "chat",
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
],
},
},
)
events = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
{
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
botId: "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
role: "user",
content: "Where is my order?",
metadata: {
user_attributes: { email: "[email protected]" },
channel: "chat",
},
artifacts: {
promptVersionId: "11111111-1111-4111-8111-111111111111",
knowledgeSnapshotId: "22222222-2222-4222-8222-222222222222",
knowledgeArticleDraftIds: [
"33333333-3333-4333-8333-333333333333",
],
ruleVersionIds: [
"44444444-4444-4444-8444-444444444444",
],
},
}),
}
);
const events = await response.json();
[
{
"id": "evt_01J4W6B9Y8P2W1K4N5Q6R7S8T9",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036800000,
"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": "evt_01J4W6C1D2E3F4G5H6J7K8L9M0",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036802400,
"role": "finibot",
"type": "message",
"message": "Your order is currently in transit and is expected to arrive tomorrow.",
"externalId": null,
"externalCreatedAt": null,
"csatRating": null,
"feedback": null,
"approved": null,
"resolved": null,
"attachments": [
{
"gcpUrl": "https://storage.googleapis.com/fini-attachments/signed/order-summary.pdf",
"gcpPath": "companies/acme/interactions/int_01J4W69F8W2H3J4K5M6N7P8Q9R/order-summary.pdf",
"originalUrl": "",
"contentType": "application/pdf",
"expiresAt": 1723040402400,
"sizeBytes": 184320
}
],
"tags": [
{
"id": "tag_shipping",
"name": "Shipping",
"groupId": "tag_group_topics"
}
],
"usedArticles": [
{
"id": "art_shipping_status",
"title": "Order tracking and delivery status",
"documentUrl": "https://help.example.com/order-tracking"
}
]
}
]
Conversations
Generate Answer
Send a message event into Fini and return the public events created for that submission.
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": "[email protected]"
},
"channel": "chat"
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
]
}
}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={
"botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"role": "user",
"content": "Where is my order?",
"metadata": {
"user_attributes": {"email": "[email protected]"},
"channel": "chat",
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
],
},
},
)
events = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
{
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
botId: "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
role: "user",
content: "Where is my order?",
metadata: {
user_attributes: { email: "[email protected]" },
channel: "chat",
},
artifacts: {
promptVersionId: "11111111-1111-4111-8111-111111111111",
knowledgeSnapshotId: "22222222-2222-4222-8222-222222222222",
knowledgeArticleDraftIds: [
"33333333-3333-4333-8333-333333333333",
],
ruleVersionIds: [
"44444444-4444-4444-8444-444444444444",
],
},
}),
}
);
const events = await response.json();
[
{
"id": "evt_01J4W6B9Y8P2W1K4N5Q6R7S8T9",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036800000,
"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": "evt_01J4W6C1D2E3F4G5H6J7K8L9M0",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036802400,
"role": "finibot",
"type": "message",
"message": "Your order is currently in transit and is expected to arrive tomorrow.",
"externalId": null,
"externalCreatedAt": null,
"csatRating": null,
"feedback": null,
"approved": null,
"resolved": null,
"attachments": [
{
"gcpUrl": "https://storage.googleapis.com/fini-attachments/signed/order-summary.pdf",
"gcpPath": "companies/acme/interactions/int_01J4W69F8W2H3J4K5M6N7P8Q9R/order-summary.pdf",
"originalUrl": "",
"contentType": "application/pdf",
"expiresAt": 1723040402400,
"sizeBytes": 184320
}
],
"tags": [
{
"id": "tag_shipping",
"name": "Shipping",
"groupId": "tag_group_topics"
}
],
"usedArticles": [
{
"id": "art_shipping_status",
"title": "Order tracking and delivery status",
"documentUrl": "https://help.example.com/order-tracking"
}
]
}
]
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
string
required
Bearer token containing your Fini workspace API key. Format:
Bearer fini_... The key needs write scope.Body parameters
string
required
Message text to add as the incoming event.
string
default:"user"
Event role. Allowed values are
user, agent, finibot, and otherbot. Most public callers should use user.string
Existing conversation ID to continue. If omitted, provide
botId and Fini will create or resolve a conversation for that bot.string
Agent ID to use when starting a new conversation. Required when
interactionId is omitted.object
object
Optional generation artifacts to use for this answer. Use this when you want Fini to answer with a specific prompt draft, knowledge snapshot, article drafts, or rule versions.
Public file attachments are not accepted by
Generate Answer. Use artifacts for prompt, knowledge, and rule-version inputs that affect answer generation.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": "[email protected]"
},
"channel": "chat"
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
]
}
}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={
"botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"role": "user",
"content": "Where is my order?",
"metadata": {
"user_attributes": {"email": "[email protected]"},
"channel": "chat",
},
"artifacts": {
"promptVersionId": "11111111-1111-4111-8111-111111111111",
"knowledgeSnapshotId": "22222222-2222-4222-8222-222222222222",
"knowledgeArticleDraftIds": [
"33333333-3333-4333-8333-333333333333"
],
"ruleVersionIds": [
"44444444-4444-4444-8444-444444444444"
],
},
},
)
events = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/hc-interactions/events/public",
{
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
botId: "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
role: "user",
content: "Where is my order?",
metadata: {
user_attributes: { email: "[email protected]" },
channel: "chat",
},
artifacts: {
promptVersionId: "11111111-1111-4111-8111-111111111111",
knowledgeSnapshotId: "22222222-2222-4222-8222-222222222222",
knowledgeArticleDraftIds: [
"33333333-3333-4333-8333-333333333333",
],
ruleVersionIds: [
"44444444-4444-4444-8444-444444444444",
],
},
}),
}
);
const events = await response.json();
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 insideevents[] on List conversations.
The request body sends incoming text as
content. Public event responses expose stored event text as message, including both the user event created from your content and any Fini reply generated for that turn.array
Array of public events created for the submission.
Show PublicEvent object
Show PublicEvent object
string
Event ID.
string
ID of the conversation the event belongs to. Pass it as
interactionId on the next request to continue the same conversation.integer
Event creation time in Unix epoch milliseconds.
string
Event role such as
user, finibot, agent, or otherbot.string
Event type such as
message, internalnote, no_reply, silent_escalation, debounce, or widget_form.string | null
Message content stored on the event, when present. This is the response-side field name for event text; the request body field is
content.string | null
Provider-side message ID when available.
integer | null
Provider-side timestamp in Unix epoch milliseconds when available.
number | null
Numeric CSAT value attached to the event, when present.
string | null
Free-text feedback note stored on the event, when present.
boolean | null
Thumbs up (
true), thumbs down (false), or unrated (null).boolean | null
Resolution flag stored on the event, when present.
array
File attachments on the event. When present, signed attachment URLs are refreshed before the response is returned.
Show attachment object
Show attachment object
string
Current signed URL for downloading the attachment.
string
Internal storage path for the attachment.
string
Original source URL recorded for the attachment.
string
MIME type of the attachment.
integer
Unix epoch milliseconds when the signed download URL expires.
integer
File size in bytes when available.
array
The
attachments, tags, and usedArticles arrays can be intentionally empty
for events that do not include files, labels, or retrieved articles.[
{
"id": "evt_01J4W6B9Y8P2W1K4N5Q6R7S8T9",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036800000,
"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": "evt_01J4W6C1D2E3F4G5H6J7K8L9M0",
"interactionId": "int_01J4W69F8W2H3J4K5M6N7P8Q9R",
"createdAt": 1723036802400,
"role": "finibot",
"type": "message",
"message": "Your order is currently in transit and is expected to arrive tomorrow.",
"externalId": null,
"externalCreatedAt": null,
"csatRating": null,
"feedback": null,
"approved": null,
"resolved": null,
"attachments": [
{
"gcpUrl": "https://storage.googleapis.com/fini-attachments/signed/order-summary.pdf",
"gcpPath": "companies/acme/interactions/int_01J4W69F8W2H3J4K5M6N7P8Q9R/order-summary.pdf",
"originalUrl": "",
"contentType": "application/pdf",
"expiresAt": 1723040402400,
"sizeBytes": 184320
}
],
"tags": [
{
"id": "tag_shipping",
"name": "Shipping",
"groupId": "tag_group_topics"
}
],
"usedArticles": [
{
"id": "art_shipping_status",
"title": "Order tracking and delivery status",
"documentUrl": "https://help.example.com/order-tracking"
}
]
}
]
Errors
400 Bad Request
400 Bad Request
The body is malformed. Common causes are omitting
content, or omitting both interactionId and botId.401 Unauthorized
401 Unauthorized
The API key is missing, malformed, revoked, or invalid. Confirm you are sending
Authorization: Bearer fini_... with the full key.403 Forbidden
403 Forbidden
The API key does not include the
write scope required for this route.500 Internal Server Error
500 Internal Server Error
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.Was this page helpful?