To ensure the security and privacy of your data, our API requires authentication for every request. Authentication is performed in two possible ways, one by including an API key in the header of your request and the other requires 3 headers and it will be used if you are trying to integrate a new APP to Darwin.
Your unique API key is provided directly by the Darwin team. This key acts as a secure access token for your account and should be kept confidential. Do not share your API key publicly or with unauthorized individuals.
If you have not received your API key or have lost it, please contact our support team at it@getdarwin.ai for assistance.
To authenticate your API requests, include your API key in the header of each request using the X-API-KEY field. Here is an example of how to include your API key in a request using cURL:
curl -X GET 'https://api.getdarwin.ai/endpoint' \
-H 'X-API-KEY: YourApiKeyHere'
Replace YourApiKeyHere with your actual API key provided by the Darwin team.
If you are trying to integrate a new APP to Darwin, you will need to obtain an APP Key and APP Secret. These keys are provided directly by the Darwin team. These keys act as a secure access token for your APP and should be kept confidential. Do not share your APP Key and APP Secret publicly or with unauthorized individuals.
If you have not received your APP Key and APP Secret or have lost them, please contact our support team at it@getdarwin.ai for assistance.
You will need to send three headers in your request to authenticate your APP requests. These headers are X-APP-KEY, X-SIGNATURE, and X-AGENT-ID.
To generate the X-SIGNATURE you will need to use the APP Key, APP Secret, and the payload of the request. Here is an example of how to do that:
const crypto = require('crypto');
const payload = JSON.stringify(request.body);
const signature = crypto.createHmac('sha256', 'your_app_secret')
.update('your_app_key' + payload)
.digest('hex');
The Darwin API uses webhooks to push events to your external systems. You can manage webhook subscriptions via the API, specifying a target URL and a list of event topics.
Darwin uses a hierarchical topic structure. You may subscribe to specific events (e.g., session.opened) or use wildcards (*) to subscribe to a category of events.
Note on Terminology: The API uses the legacy term forwarded in event keys. In the current Darwin domain model, this represents a Session Transfer (handing off the session due to qualification, escalation, or recovery).
session.opened: Triggered when a new session starts.session.closed: Triggered when a session ends (typically due to inactivity).session.closed.unforwarded: Triggered when a session closes without being transferred to an agent or external flow.session.analyzed: Triggered when smart fields are calculated and the conversation summary is generated.session.stage.transitioned: Triggered when a session moves between pipeline stages.session.*: Wildcard. Subscribes to all session lifecycle and transfer events.session.forwarded: Generic event triggered when a session is transferred for any reason.session.forwarded.qualified: The session was transferred because it met qualification criteria.session.forwarded.escalated: The session was transferred via an escalation path.session.forwarded.recovered: The session was transferred as part of a recovery flow.function.call.<functionName>: Triggered when a specific function is executed.function.call.*: Wildcard. Subscribes to all function calls.function.*: Wildcard. Subscribes to all function-related events.To ensure events originated from Darwin and were not tampered with, all webhook requests include a cryptographic signature.
X-SIGNATURECompute the HMAC-SHA256 of the raw request body using your webhook secret. Compare your computed hash with the value in the X-SIGNATURE header. If they match, the payload is authentic. Here's an example of how to do that in Node.js:
const crypto = require('crypto');
const payload = JSON.stringify(request.body);
const expectedSignature = crypto.createHmac('sha256', 'your_app_secret')
.update(payload)
.digest('hex');
if (receivedSignature !== expectedSignature) {
throw new Error('Invalid signature');
}
All webhooks have the following properties:
The Darwin API provides an endpoint for configuring new webhooks, which are essential for creating real-time, event-driven integrations between the Darwin platform and external systems. Webhooks allow external services to receive notifications from Darwin immediately after specific events occur, facilitating automated processes and seamless data flows.
Request body
| webhookUrl required | string The URL of the webhook to send events to. |
| types required | Array of strings Items Enum: "session.opened" "session.closed" "session.forwarded" "session.analyzed" "session.*" "function.call.<functionName>" "function.call.*" "function.*" The types of events to send to the webhook. You can use wildcards to match multiple events. |
{- "types": [
- "session.opened",
- "session.closed",
- "session.forwarded",
- "session.analyzed",
- "session.*",
- "function.call.*"
]
}{- "secret": "ouisndnv8329r27dsvs_2389svkjs",
- "webhookId": 1
}The "Get all webhooks" API endpoint is designed to provide users with the ability to retrieve a comprehensive list of all the webhooks they have set up. This is particularly useful for managing and auditing webhooks, allowing users to see which events they are subscribed to.
[- {
- "types": [
- "session.opened",
- "session.closed",
- "function.call.*"
]
},
]The "Update an existing webhook" operation in the Darwin API allows users to modify the settings or parameters of a webhook they have previously configured.
| id required | string (id) ID of the webhook to update |
Request body
| webhookUrl required | string The URL of the webhook to send events to. |
| types required | Array of strings Items Enum: "session.opened" "session.closed" "session.forwarded" "session.analyzed" "session.*" "function.call.<functionName>" "function.call.*" "function.*" The types of events to send to the webhook. You can use wildcards to match multiple events. |
{- "types": [
- "session.opened",
- "session.closed",
- "session.forwarded",
- "session.analyzed",
- "session.*",
- "function.call.*"
]
}{ }Remove an existing webhook refers to the process of deleting a previously configured webhook, allowing users to clean up unnecessary or outdated webhooks and maintain a streamlined integration.
| id required | string (id) ID of the webhook to remove |
{ }As for function calls and function returns, they are customized abilities and skills that can be added to Darwin AI according to the client's needs, for example, integration to the user's calendar to schedule appointments.
| id required | string (id) ID of the function call to update |
Request body
| returnData | object Data to be returned from the function call. This will be used to update the response of a function call so that the agent can use the data to generate a response. |
{- "returnData": {
- "weather": "sunny",
- "temperature": 25
}
}{- "functionCallId": "1234"
}The Darwin API allows for sending outbound messages through a specific endpoint, when there is an action that triggers it. For this, you have to provide specific information, such as the channel, channel type options, and the templateId will be provided by Darwin AI. Responses to this request can include a 200 status code with the body containing the channelId, indicating successful message delivery, or a 400 status code indicating an error.
| id required | string (id) ID of the thread to send the message to. This is threadId is a unique identifier for the destination of the message. Like a phone number for WhatsApp or a user ID for Facebook Messenger. |
Request body
| channel required | string The ID of the channel to use for sending the message. |
| templateId required | string Required for templated channels like wa-gupshup. The ID of the template to use for sending the message. |
| templateParams required | Array of strings Required for templated channels like wa-gupshup. The parameters to use for the template. |
| message required | string Required for non-templated channels. The message to send. |
| mediaUrl | string <url> Optional. The publicly accessible URL of the media file (image, video, document) to be included in the message header. |
| mediaType | string Enum: "image" "video" "document" Optional. The type of media specified in mediaUrl. Required if mediaUrl is provided. |
| location | string Optional. The location of the user. |
| initialState | string Deprecated The initial state to set for the conversation. |
number or string The initial pipeline to set for the conversation. | |
object The source of the message. Include all pertinent utm_parameters or other tracking information. |
{- "channel": "1234",
- "message": "Hello, how can I help you?",
- "initialPipelineId": 1234,
- "source": {
- "utm_source": "website",
- "utm_medium": "chat",
- "utm_campaign": "summer_sale",
- "utm_term": "shoes",
- "utm_content": "cta",
- "intent": "outbound",
- "interest": "SKU-1234"
}
}{- "channelId": "1234"
}Get all channels available to use for sending messages. This endpoint will return a list of all channels available to use for sending messages.
[- {
- "id": "1",
- "name": "WhatsApp Unofficial",
- "capabilities": {
- "templated": false,
- "outboundMessages": true
}
}, - {
- "id": "2",
- "name": "Instagram",
- "capabilities": {
- "templated": false,
- "outboundMessages": false
}
}, - {
- "id": "3",
- "name": "WhatsApp Gupshup",
- "capabilities": {
- "templated": true,
- "outboundMessages": true
}
}
]Get templates available for a provided channel to use for sending messages. This endpoint will return a list of all templates available for a provided channel.
| id required | string (id) ID of the channel to get templates for |
[- {
- "id": "1234",
- "name": "Appointment Reminder",
- "messageBody": "Hello {0}, your appointment is scheduled for {1}.",
- "numberOfPlaceholders": 2
}, - {
- "id": "5678",
- "name": "Payment Confirmation",
- "messageBody": "Hello {0}, your payment of {1} has been confirmed.",
- "numberOfPlaceholders": 2
}
]Get all available smart fields for agent. This endpoint will return a list of all available smart fields for the agent.
[- {
- "name": "name",
- "description": "The name of the user",
- "type": "string"
}, - {
- "name": "email",
- "description": "The email of the user",
- "type": "string"
}, - {
- "name": "phone",
- "description": "The phone number of the user",
- "type": "string"
}
]Get all available source parameters for agent. This endpoint will return a list of all available source parameters for the agent.
[- "utm_term",
- "utm_content",
- "interest"
]Get metadata of the app regarding a provided conversation. This endpoint will return a list of all metadata of the app regarding a provided conversation.
| id required | string (id) ID of the agent_app to get metadata for. This is the ID of the particular installation of the app for a specific agent. |
| conversation_id | string (conversation_id) Conversation ID |
[- {
- "conversation_id": "1234-56789012",
- "metadata": {
- "name": "John Doe",
- "age": 30
}
}, - {
- "conversation_id": "5678-12345678",
- "metadata": {
- "name": "Jane Doe",
- "age": 25
}
}
]Save metadata of the app regarding a provided conversation. This endpoint will save metadata of the app regarding a provided conversation.
| id required | string (id) ID of the agent_app to save metadata for. This is the ID of the particular installation of the app for a specific agent. |
Request body
| metadata required | object Metadata to save regarding the provided conversation. This can be any data that the app wants to store for the conversation. |
| conversation_id required | string The ID of the conversation to save the metadata for. |
{- "metadata": {
- "name": "John Doe",
- "age": 30
}, - "conversation_id": "1234-56789012"
}{- "appContactDataId": "1234"
}The Darwin API utilizes Semantic Versioning in the format major.minor.patch. The current major version is incorporated into the API request path as /v1/. Non-breaking minor and patch updates to the API are released regularly. These may include new endpoints, data points, and API plan features which are always introduced in a non-breaking manner. This means you can expect new properties to become available in our existing /v1/ endpoints however any breaking change will be introduced under a new major version of the API with legacy versions supported indefinitely unless otherwise stated.
Retrieves the last N webhook events for a given event type and agent ID.
[- {
- "eventType": "string",
- "agentId": "string",
- "agentName": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": { }
}
]