Generate Answer

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"
      }
    ]
  }
]

POST

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

Optional conversation metadata to merge into the request state.

Show metadata properties

object

User attributes to merge into the conversation metadata for this submission.

string

Optional channel override. Allowed values are chat and email.

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.

Show artifacts properties

string

Prompt version ID to use for answer generation.

string

Knowledge snapshot ID to use for retrieval.

string[]

Knowledge article draft IDs to include in retrieval.

string[]

Rule version IDs to use while evaluating the reply flow.

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 inside events[] 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

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

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

Tags attached to the event.

Show tag object

string

Tag ID.

string

Tag name.

string | null

Parent tag-group ID when one exists.

array

Public article references retrieved for that event.

Show article object

string

Article ID.

string

Article title.

string | null

Source document URL when available.

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

The body is malformed. Common causes are omitting content, or omitting both interactionId and botId.

401 Unauthorized

The API key is missing, malformed, revoked, or invalid. Confirm you are sending Authorization: Bearer fini_... with the full key.

403 Forbidden

The API key does not include the write scope required for this route.

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.

​Headers

​Body parameters

​Request example

​Response

​Errors

Headers

Body parameters

Request example

Response

Errors