vtexdocs · mariananantua · Mar 19, 2026
diff --git a/docs/guides/Weni-by-VTEX/weni-events-api-guide/using-the-weni-events-api b/docs/guides/Weni-by-VTEX/weni-events-api-guide/using-the-weni-events-api
@@ -0,0 +1,294 @@
+---
+title: "Using the Weni Events API"
+slug: "using-the-weni-events-api"
+hidden: false
+createdAt: "2025-03-19T12:00:00.000Z"
+updatedAt: "2025-03-19T13:11:00.000Z"
+excerpt: "Learn how to query and send events to the Weni Nexus Data system using the Events API.
+---
+
+This guide explains how to use the Weni Events API to retrieve events from a time range and to send events to the Nexus Data data lake. You will learn how to authenticate your token, which parameters to use, how to structure requests, and how to work with custom and fixed events.
+
+This guide contains the following sections:
+
+- [Understanding the events](#understanding-the-events)
+- [Retrieving events](#retrieving-events)
+- [Sending events](#sending-events)
+
+## Understanding the events
+
+The Weni Events API is the interface for the Weni Nexus Data events system. Events are structured data objects that capture information about conversations, agent interactions, tool usage, and user feedback. All events follow a common structure.
+
+### Authenticating
+
+In order to [retrieve events using the API](#retrieving-events) or to [send events from an action group](#sending-events), you must use the API Token for your account. You can find it under **Applications > Other Apps** in the VTEX Agentic CX Platform. You must include the word `Token` in the request `Authorization` parameter followed by your API token: `Authorization: Token <YOUR_API_TOKEN>`.
+
+> ℹ️ Check with your service provider to confirm what permissions are required to use this API.
+
+### Types of events
+
+There are two types of events:
+
+- **[Fixed events](#fixed-events):** Events generated by Weni, such as Resolution, Topics, Tool Calls, and Agent Invocation.
+- **[Custom events](#custom-events):** Events that you have defined, sent from action groups, such as CSAT, NPS, and custom user events.
+
+Every event uses the following structure:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `event_name` | string | The name of the event will always be `weni_nexus_data` for all events. |
+| `key` | string | Type of the event (such as `weni_csat`, `weni_nps`, `topics`, `tool_call`, `agent_invocation`, or a custom key). |
+| `date` | string | Timestamp when the event occurred in ISO 8601 format. |
+| `contact_urn` | string | Contact identifier in URN format. If omitted, the Weni system will add it. |
+| `value_type` | string | Type of the `value` field: `string`, `number`, `boolean`, `object`, or `array`. |
+| `value` | string | Main value of the event. Its type must match `value_type`. |
+| `project` | string | UUID of the project. If omitted, the Weni system will add it. When retrieving events, this field might not be in the response. |
+| `metadata` | object | Additional context about the event. The `metadata` structure depends on the event type. Can be an empty object `{}`. |
+
+### Fixed events
+
+Fixed events are generated by Weni to track specific actions.
+
+> ℹ️ You cannot send fixed events, you can only retrieve information about fixed events using the [Retrieve events](https://developers.vtex.com/docs/api-reference/weni-by-vtex-api#get-/api/v2/events.json) endpoint.
+
+| Event type | Key | Description |
+| --- | --- | --- |
+| Resolution | `conversation_classification` | Tracks the resolution status of a conversation in the `value` field: <br> `Resolved`: The conversation was successfully resolved. <br> `Unresolved`: The conversation could not be resolved. <br> `In Progress`: The conversation is still being processed. <br> `Unclassified`: "The conversation has not been classified yet". <br> `Has Chat Room`: The conversation required human support. <br> Metadata includes: <br> `human_support`: Informs whether the conversation had human support. If it had human support, it is set to `true`; if not, it is set to `false`. When it is set to `true`, the status is automatically set to `Has Chat Room`. |
+| Topics | `topics` | Tracks the topics and subtopic classification of a conversation, such as Billing, Support, Technical and others. If no topics are configured or classification fails, the `value` is set to `bias`. Metadata includes: <br> `topic_uuid`: Unique ID of the topic. <br> `subtopic_uuid`: Unique ID of the subtopic. <br> `subtopic`: String with the topic of conversation. <br> `human_support`: Informs whether the conversation had human support. If it had human support, it is set to `true`; if not, it is set to `false`. |
+| Tool call | `tool_call` | Tracks when an agent invokes a tool (action group). Metadata includes: <br> `backend`: The format of the backend, such as OpenAI. <br> `foundation_model`: The model used by the tool, such as `gpt-4` or `anthropic.claude-3-sonnet-20240229-v1:0`. <br> `tool_call`: Array containing information about the tool's name, function, and parameters. |
+| Agent invocation | `agent_invocation` | Tracks when the supervisor agent delegates to a collaborator agent. Metadata includes: <br> `backend`: The format of the backend, such as OpenAI. <br> `foundation_model`: The model used by the tool, such as `gpt-4` or `anthropic.claude-3-sonnet-20240229-v1:0`. <br> `agent_collaboration`: Array containing information about the agents's name and the input text sent to the collaborator agent. |
+
+### Custom events
+
+Custom events are events sent from action groups.
+
+#### CSAT (Customer Satisfaction) score
+
+Besides the required parameters (`date_start` and `date_end`), you must also use these parameters:
+
+- `key`: Must be set to `weni_csat`.
+- `value_type`: Must be set to `string`.
+- `value`: Must be set to a CSAT Score, which ranges from `1` to `5`. Each number indicates a level of satisfaction, as described below:
+ - `1`: Very unsatisfied
+ - `2`: Unsatisfied
+ - `3`: Neutral
+ - `4`: Satisfied
+ - `5`: Very satisfied
+- `metadata`: The system automatically sets this field with the value `"agent_uuid": "special-csat-agent-uuid"` from the project settings.
+
+See an example of a request below:
+
+```json
+{
+ "event_name": "weni_nexus_data",
+ "date": "2026-01-15T10:30:00-03:00",
+ "project": "550e8400-e29b-41d4-a716-446655440000",
+ "contact_urn": "tel:+5511999999999",
+ "key": "weni_csat",
+ "value_type": "string",
+ "value": "5",
+ "metadata": {
+ "agent_uuid": "special-csat-agent-uuid"
+ }
+}
+```
+
+#### NPS (Net Promoter Score)
+
+You can use this endpoint to track the NPS from users.
+
+Besides the required parameters (`date_start` and `date_end`), you must also use these parameters:
+
+- `key`: Must be set to `weni_nps`.
+- `value_type`: Can be set to `string` or `number`, depending on how you send the value. For example, if you send `value: 8`, set `value_type: "number"`; if you send `value: "8"`, set `value_type: "string"`.
+- `value`: Must be set to an NPS value, which ranges from `1` to `10`. Can be sent as number or string.
+- `metadata`: The system automatically sets this field with the value `"agent_uuid": "special-nps-agent-uuid"` from the project settings.
+
+See an example of a request below:
+
+```json
+{
+ "event_name": "weni_nexus_data",
+ "date": "2024-01-15T10:30:00-03:00",
+ "project": "550e8400-e29b-41d4-a716-446655440000",
+ "contact_urn": "tel:+5511999999999",
+ "key": "weni_nps",
+ "value_type": "string",
+ "value": "8",
+ "metadata": {
+    "agent_uuid": "special-nps-agent-uuid"
+    }
+}
+```
+
+#### User-specific events
+
+You can use this endpoint to track events using your own set of fields. You can send multiple events in a single action group response.
+
+Besides the required parameters (`date_start` and `date_end`), you must also use these parameters:
+
+- `key`: Must be set to any custom value that is not a reserved key. Reserved keys are: `weni_csat`, `weni_nps`, `conversation_classification`, `topics`, `tool_call`, `agent_invocation`.
+
+>⚠️ Reserved keys fetch specific data and cannot be used to track custom events.
+
+- `value_type`: The type of the value you send (boolean, number, string, object).
+- `value`: The custom value of your choice. The type of the value must match the `value_type` field.
+- `metadata`: The object of the custom metadata. Can include any field. You can use this object to include useful context about your event.
+
+If you omit `metadata.agent_uuid`, the system can populate it from the agent that triggered the action.
+
+See an example of a request below:
+
+```json
+{
+ "events": [
+  {
+  "event_name": "weni_nexus_data",
+  "date": "2025-11-15T10:30:00-03:00",
+  "project": "550e8400-e29b-41d4-a716-446655440000",
+  "contact_urn": "tel:+5511999999999",
+  "key": "custom-event-key",
+  "value_type": "value-type",
+  "value": "custom-value",
+  "metadata": {
+    "agent_uuid": "agent-uuid-here",
+    // Any additional custom fields
+    "custom_field": "custom_value"
+    }
+  }
+ ]
+}
+
+```
+
+---
+
+## Retrieving events
+
+The [Retrieve events](https://developers.vtex.com/docs/api-reference/weni-by-vtex-api#get-/api/v2/events.json) endpoint allows you to fetch events recorded within a specific time period.
+
+This endpoint has only two required parameters: `date_start` and `date_end`. All other filters are optional. We recommend using more filters to improve API performance and using the `limit` field to avoid large responses.
+
+### Request body with one filter
+
+See below a request body example with a `limit` filter:
+
+```shell
+curl --request GET \
+ --url 'https://flows.weni.ai/api/v2/events?date_start=2025-09-05T00%3A00%3A00Z&date_end=2025-09-05T23%3A29%3A29Z&limit=5' \
+ --header 'Authorization: Token <API_TOKEN>' \
+ --header 'Content-Type: application/json'
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `date_start` | string | Start date of the event. |
+| `date_end` | string | End date of the event. |
+| `limit` | integer | Maximum number of events returned. |
+
+### Request body with multiple filters
+
+See below a request body example using multiple filters:
+
+```shell
+curl --request GET \
+ --url 'https://flows.weni.ai/api/v2/events?date_start=2025-09-01T00%3A00%3A00Z&date_end=2025-09-05T23%3A59%3A59Z&key=weni_csat&contact_urn=whatsapp%3A5511999999999&limit=10' \
+ --header 'Authorization: Token <API_TOKEN>' \
+ --header 'Content-Type: application/json'
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `date_start` | string | Start date of the event. |
+| `date_end` | string | End date of the event. |
+| `key` | string | Type of the event. |
+| `contact_urn` | string | Contact identifier in URN format. |
+
+---
+
+## Sending events
+
+You can also send one or more events by having an action group return an `events` array in its response. The system extracts these events, enriches them with `project` and `contact_urn` when they are omitted, and sends them to the data lake.
+
+### How it works
+
+1. An action group (lambda function) runs and returns a JSON response.
+2. If the response contains an `events` array, the system parses it.
+3. For each event, the system adds `project` and `contact_urn` if missing, and can add `metadata.agent_uuid` when relevant.
+4. Events are sent to the data lake (e.g. via the send-data-lake task).
+
+### Sending events from an action group
+
+1. From your action group, return a JSON body that includes an `events` array. Each event must follow the event structure and include the required fields.
+2. Set the request headers when calling the API (if you call it explicitly):
+
+- `Content-Type`: `application/json`
+- `Authorization`: `Token <API_TOKEN>`
+
+3. If you use the GET endpoint to ingest, send a `GET` request to `https://flows.weni.ai/api/v2/events.json` with the body and headers above.
+4. Check the response:
+
+- **202:** The request was accepted. The response body includes an `accepted` field with the number of events accepted.
+- **400:** The request body is invalid. The response includes an `error` field with a message (e.g. missing required field `key`).
+
+### Example: action group response with events
+
+```json
+{
+ "events": [
+ {
+ "event_name": "weni_nexus_data",
+ "key": "weni_csat",
+ "value_type": "string",
+ "value": "5",
+ "metadata": {}
+ },
+ {
+ "event_name": "weni_nexus_data",
+ "key": "product_purchase",
+ "value_type": "string",
+ "value": "product-123",
+ "metadata": {
+    "price": 99.99,
+    "category": "electronics"
+    }
+ }
+]
+}
+```
+
+### Example responses
+
+**Success (202):**
+
+```json
+{
+ "accepted": 2
+}
+```
+
+**Error (400):**
+
+```json
+{
+ "error": "Invalid event structure: missing required field 'key'."
+}
+```
+
+### Additional resources
+
+- Data Lake SDK: `weni_datalake_sdk`
+- Event path: `EventPath` from `weni_datalake_sdk.paths.events_path`
+- Adapter classes: `OpenAIDataLakeEventAdapter` (OpenAI backend), `BedrockDataLakeEventAdapter` (Bedrock backend)
+
+## Possible errors when Sending events
+
+See below which errors can be returned when attempting to [send an event](#sending-events) and how to avoid or work around them.
+
+| Error code and message | What to do |
+| --- | :--- |
+| **400 Bad Request** | Check that each event includes all required fields: `event_name`, `key`, `value_type`, `value`, `metadata`. Ensure `value` matches `value_type` and `event_name` is `weni_nexus_data`. |
+| **Authentication errors** | Confirm that your API token under **Applications > Other Apps** is correct and sent in the `Authorization` header as `Token <API_TOKEN>`. |
+| **Permissions error** | If you cannot access the API or certain operations, check with your service provider if you have the required permissions. |
+| **Events not appearing in data lake** | Events are not sent in preview mode. Verify the action group returns valid JSON and that each event has the required structure. Check application logs for errors during event processing. |
+| **CSAT/NPS not updating conversation** | Ensure the key is exactly `weni_csat` or `weni_nps`, since this field is case-sensitive. CSAT values must be strings: `"1"` to `"5"`. NPS must be integers: `0` to `10`. Verify database connectivity. |