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:

All requests require a valid access token. See 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:

# 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

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 -- Token generation and lifecycle
• Chat API -- Full chat endpoint reference
• Dashboard HTTP API -- Dashboard trigger endpoints
• Getting Started -- API quickstart guide