API trigger

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

1. 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.

2. 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.

3. 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.