> Source: https://builder-docs.ema.ai/api-reference/triggers
> Title: Triggering AI Employees

# Triggering AI Employees

Ema's APIs allow you to invoke AI Employees programmatically, making it straightforward to set up **recurring (scheduled) triggers** and **event-based triggers** from external platforms. This guide covers common patterns for both approaches.

## Overview

Any system that can make HTTP requests can trigger an Ema AI Employee. The two most common patterns are:

-   **Recurring triggers** -- Run an AI Employee on a schedule (e.g., every hour, daily, weekly).
-   **Event-based triggers** -- Run an AI Employee in response to an external event (e.g., a new lead is created in Salesforce, a support ticket is opened in Zendesk).

Both patterns use the same Ema APIs under the hood. The difference is in _what_ initiates the API call.

## API Endpoints for Triggering

Depending on your AI Employee type, use the appropriate endpoint:

AI Employee Type

Endpoint

Method

Chat

`/api/{tenantId}/chat/` (create conversation) then `/api/{tenantId}/chat/{conversationId}` (send message)

POST

Dashboard

`/api/personas/{persona_id}/dashboard/upload-and-run-rows`

POST

All requests require a valid access token. See [Authentication](/legacy-docs/api-reference/authentication) for how to generate and refresh tokens.

## Recurring Triggers

Use a scheduler in your platform of choice to call Ema's API at a fixed interval.

### Option 1: Cron-Based Schedulers

If you have access to a server or cloud environment, use a cron job or cloud scheduler to make API calls on a schedule.

-   **Linux/macOS cron** -- Add a crontab entry that runs a `curl` command to trigger the AI Employee at the desired interval.
-   **Google Cloud Scheduler** -- Create a job that sends an HTTP POST to Ema's API endpoint on a cron schedule. Configure the Authorization header with your Ema access token.
-   **AWS EventBridge Scheduler** -- Create a schedule rule that invokes a Lambda function (or directly targets an HTTP endpoint via API Destination) to call Ema's API.
-   **Azure Logic Apps** -- Use the Recurrence trigger to run a workflow on a schedule, then add an HTTP action to call Ema's API.

### Option 2: Workflow Automation Platforms

No-code platforms can schedule API calls without any infrastructure:

-   **Zapier** -- Use the "Schedule by Zapier" trigger (every hour, day, or week), then add a Webhooks action to POST to Ema's API.
-   **Make (Integromat)** -- Use the "Schedule" module as the trigger, followed by an HTTP module to call Ema's API.
-   **n8n** -- Use the Cron node to trigger a workflow on a schedule, then use the HTTP Request node to call Ema's API.
-   **Power Automate** -- Use the "Recurrence" trigger to run a flow on a schedule, then add an HTTP action to invoke Ema.

### Example: Recurring Chat Trigger

This example creates a new conversation and sends a message to an AI Employee on a schedule:

```bash
# Step 1: Generate an access token
ACCESS_TOKEN=$(curl -s -X POST https://your-instance.ema.co/api/auth/generate_access_token \
 -H "x-ema-api-key: your-api-key" \
 -H "Content-Type: application/json" | jq -r '.access_token')

# Step 2: Create a conversation
CONVERSATION_ID=$(curl -s -X POST https://your-instance.ema.co/api/<tenant_id>/chat/ \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"persona_id": "<persona-uuid>"}' | jq -r '.conversation_id')

# Step 3: Send a message to trigger the AI Employee
curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/$CONVERSATION_ID \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"message": "Generate the daily sales summary report."}'
```

## Event-Based Triggers

Event-based triggers invoke an AI Employee when something happens in an external system -- a new record is created, a status changes, or a threshold is crossed.

### Pattern: Webhook to Ema

Most platforms support outbound webhooks or event notifications. The general pattern is:

1.  Configure the external platform to fire a webhook (or event notification) when the trigger condition is met.
2.  Point the webhook at a lightweight middleware (e.g., a serverless function, Zapier, or Make) that transforms the event payload into an Ema API call.
3.  The middleware authenticates with Ema and sends the relevant data to the AI Employee.

### Example Scenarios

External Event

Platform

How to Connect

New lead created

Salesforce

Use Salesforce Flow or Outbound Messages to call a webhook that triggers an Ema AI Employee to enrich and qualify the lead.

Support ticket opened

Zendesk / Freshdesk

Configure a webhook trigger on ticket creation that sends ticket details to Ema for auto-triage or draft response.

New hire added to HRIS

Workday / BambooHR

Use the platform's event notification or a polling integration to trigger Ema's onboarding AI Employee.

Deal stage changed

HubSpot

Use HubSpot Workflows to trigger a webhook when a deal moves to a specific stage, invoking Ema to generate next-step recommendations.

Form submission

Typeform / Google Forms

Use native webhook integrations or Zapier to forward submission data to Ema for processing.

Document uploaded

Google Drive / SharePoint

Use Google Drive push notifications or SharePoint webhooks to trigger Ema's document analysis AI Employee.

Scheduled report ready

Snowflake / BigQuery

Use a cloud function triggered by query completion to send results to Ema for summarization.

### Example: Salesforce Lead to Ema

Using Zapier as middleware:

1.  **Trigger:** "New Record" in Salesforce (object: Lead).
2.  **Action 1:** Webhooks by Zapier -- POST to `/api/auth/generate_access_token` to get a token.
3.  **Action 2:** Webhooks by Zapier -- POST to `/api/{tenantId}/chat/` to create a conversation.
4.  **Action 3:** Webhooks by Zapier -- POST to `/api/{tenantId}/chat/{conversationId}` with the lead details as the message body.

The same pattern works with Make, n8n, Power Automate, or a custom serverless function (AWS Lambda, Google Cloud Functions, Azure Functions).

## Best Practices

-   **Token management:** Access tokens expire (24 hours for global API keys, 30 minutes for chatbot keys). Build in token refresh logic, especially for recurring triggers.
-   **Idempotency:** For event-based triggers, consider deduplication. Some platforms may retry webhook delivery, which could invoke the AI Employee multiple times for the same event.
-   **Error handling:** Log API responses from Ema. If a trigger fails, implement retry logic with exponential backoff.
-   **Payload mapping:** When passing external event data to Ema, format the message clearly so the AI Employee can parse and act on it. Include relevant record IDs, names, and context.
-   **Security:** Store API keys securely (use secrets managers, not plain text). Restrict webhook endpoints with IP allowlisting or signature verification where possible.

## Related

-   [Authentication](/legacy-docs/api-reference/authentication) -- Token generation and lifecycle
-   [Chat API](/legacy-docs/api-reference/chat/chat-api) -- Full chat endpoint reference
-   [Dashboard HTTP API](/legacy-docs/api-reference/dashboard/http-api) -- Dashboard trigger endpoints
-   [Getting Started](/legacy-docs/api-reference/getting-started) -- API quickstart guide