API trigger

Trigger your agent directly from you apps or websites with the API trigger.

Create trigger

• API triggers are created inside agent projects.

• Each API trigger must have a unique name and unique key within the project.

• The trigger key is case-insensitive and can be customised to match an identifier meaningful for your application.

Note: Make sure the key is something easy to reference when making API calls.

Create API key

API triggers are secured by API keys that are managed by your organization.

• The API key must have at least the permission project.trigger

Best practices

• Only grant the API key access to the specific projects it needs.

• Limit the permissions to only what’s required.

Send a request

To call your trigger, send a POST request to its unique URL.

https://api.chathive.app/api/v1.0/project/:projectId/trigger/:key

This URL can be found in the trigger settings, or construct it using your project ID and trigger key.

Optionally, include a JSON body with instruction and configuration. The body will be passed to your filters.

• Be processed by the trigger’s filters.

• Be passed to your agent as input.

The api key you created must be included in the headers of the post request.

curl -X POST "https://api.chathive.app/api/v1.0/project/:projectId/trigger/:key" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "key": "value" }'

Request body

You can include a body with the trigger to give your AI agent more context when executing your request. The following fields are supported:

Status	Value	Description
instruction	string | object	Instruction that will be provided to the agent, can be a string or object
sessionId	string	Unique string generated by you to distinguished conversations. When sessionId changes all previous conversation context will be lost and it will be like a new conversation has started
environment	string	Identify in the analytics from where the request came. Default: "api"
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1
timezone	string	Accepted but request timed out before agent completed it's task. Is only returned when wait for response has been enabled and request took to long.
customer	customer data	Data to identify the current customer.
context	record<string, Boolean | number | string | undefined>	Extra context that should be used by the agent to provide accurate answers.

Response

Status	Description
200	Request has been accepted and agent completed it's task. Body will be included with final response.
202	Request has been accepted but agent is stil executing the task. Is only returned when wait for response has been disabled. /
400	Event has been dropped. The body doesn't match the filters
404	Trigger does not exist Trigger has been paused Trigger has been deleted
408	Accepted but request timed out before agent completed it's task. Is only returned when wait for response has been enabled and request took to long.

Advanced Settings

Customize trigger key

Customize the trigger key used in the API to clearly indicate which trigger is being executed in your code. Some key guidelines:

• Must be unique within your organization.

• Can only contain the following characters: a-zA-Z0-9_-.

Ignore duplicate triggers

To prevent executing the same trigger multiple times and waisting AI credits, you can enforce it to only execute triggers with a unique body. Once this is turned on, every trigger that is executed with the same body will be dropped. This will only check triggers that are executed with a body.

Wait for response

For tasks that take a long time (minutes, hours, or days), you can configure the trigger to immediately return a $(202)$ success response once the task is accepted.

This way, your server doesn't have to wait for the task to finish.