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.

Obtaining Your API Key

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.

Using Your API Key

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.

Obtaining Your APP Key and APP Secret

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.

Using Your APP Key and APP Secret

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');

Webhooks are a way for web applications to communicate with each other in real-time. They allow you to send data from one application to another as soon as an event occurs. This is useful for integrating different systems and automating processes. In the Darwin API, webhooks are used to send events to external systems when specific actions occur in the Darwin platform. For example, you can set up a webhook to receive a notification whenever a new session is opened or closed. This allows you to take immediate action based on these events. You can create, update, and remove webhooks using the Darwin API. This section provides endpoints for managing webhooks. When you create a webhook, you specify the URL of the external system that will receive the events and the types of events you want to be notified about. You can use wildcards to match multiple events. For example, you can set up a webhook to receive notifications for all session events or all function call events. Here are all events that you can subscribe to:

• session.opened: Notification received when a new session is created. A new session occurs when a conversation begins with a new WhatsApp number or when a previously closed conversation is considered as new.
• session.closed: Occurs when the conversation is closed due to client inactivity, typically set to 7 days by default but can be modified.
• session.forwarded: Notification received when a session is rated or escalated because the conversation is requested to be transferred.
• session.analyzed: Triggered once smart fields are calculated, and the conversation summary is generated.
• session.*: Wildcard to subscribe to all session events.
• function.call.: Notification received when a function call is made. You can replace <functionName> with the name of the function you want to be notified about.
• function.call.*: Wildcard to subscribe to all function call events.
• function.*: Wildcard to subscribe to all function events.

All webhooks are authenticated using a secret key that is generated when the webhook is created. This secret key is used to sign the payload of the event, ensuring that the event is sent by Darwin and not tampered with during transit. When you create a webhook, you will receive the secret key, which you should keep secure and use to verify the authenticity of the events you receive. This secret will be used to generate the X-SIGNATURE header when you receive an event from Darwin. You can verify the signature using the same method as generating it, here is an example of how to do that:

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:

• eventType: The type of event that the webhook is subscribed to. This can be one of the events listed above.
• timestamp: The timestamp when the event occurred.
• agentId: The ID of the agent that the event is related to.
• agentName: The name of the agent that the event is related to.
• data: Additional data related to the event. This can include information about the session, function call, or other event that triggered the webhook.

Session Events:

• conversationId: The ID of the conversation.
• sessionId: The ID of the session.
• channelId: The ID of the channel.
• channelName: The name of the channel.
• createdAt: The timestamp when the session was created.
• conversationThreadId: The ID of the conversation thread.
• conversationTitle: The name of the conversation.
• closedAt: The timestamp when the session was closed.
• lastHumanActivityAt: The timestamp of the last human activity in the session.
• forwardedAt: The timestamp when the session was forwarded.
• forwardedToId: The ID of the agent the session was forwarded to.
• forwardedToName: The name of the agent the session was forwarded to.
• forwardType: The type of forwarding that occurred.
• summary: The summary of the conversation.
• summarizedAt: The timestamp when the conversation was summarized.
• smartFields: The smart fields calculated for the conversation.

Function Call Events:

• inputs: The inputs provided to the function.
• functionName: The name of the function.
• functionId: The ID of the function.
• functionCallId: The ID of the function call.
• functionStatus: The status of the function call.
• sessionId: The ID of the session.
• conversationId: The ID of the conversation.
• conversationThreadId: The ID of the conversation thread.
• app: The app data related to the function call. Only available if the function is called by an app.
• • metadata: The metadata of the app.
• • agentAppId: The ID of the particular installation of the app for a specific agent.

Endpoints for managing function calls

Endpoints for managing messages

Endpoints for managing channels

Endpoints for managing Agents

Endpoints for managing apps

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.

v1.3.0 (2024-03-25)

• Added new endpoints for managing agents

v1.2.0 (2024-03-22)

• Added new authentication method for APPs

v1.1.0 (2024-03-20)

• Added new endpoints for managing channels

v1.0.0 (2024-02-01)

• Initial release of the Darwin API
• Added endpoints for managing webhooks, function calls and messages

• Added new endpoints for managing agents

• Added new authentication method for APPs

• Added new endpoints for managing channels

• Initial release of the Darwin API
• Added endpoints for managing webhooks, function calls and messages