# Entra Integration for Atonom
Source: https://docs.atonom.ai/SAML/entra
Setting up SAML single sign-on (SSO) for the Atonom application using a non-gallery configuration in your Microsoft Entra tenant.
This guide will walk you through the process of configuring SAML-based single sign-on (SSO) for the Atonom application within your Microsoft Entra ID tenant. This process involves creating a non-gallery enterprise application, configuring the necessary SAML parameters, and assigning users.
***
### **1. Create the Enterprise Application**
Since Atonom is not yet in the main Entra App Gallery, you will first need to create a new non-gallery application.
1. Sign in to the **Microsoft Entra admin center** as at least a `Cloud Application Administrator`.
2. Browse to **Identity > Applications > Enterprise applications**.
3. Select **+ New application**.
4. On the "Browse Microsoft Entra Gallery" page, select the **+ Create your own application** button at the top.
5. A pane will appear on the right. In the "What's the name of your app?" field, enter `Atonom`.
6. Select the option **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Click **Create**. Please wait a moment while the application is created and added to your tenant.
***
### **2. Get Atonom Service Provider Metadata**
1. Go to the Atonom **[Identity Management](https://app.getsignals.ai/#/v2/settings/saml)** page and keep this open in a separate tab.
### **3. Configure SAML Single Sign-On**
Once the Atonom application has been created, you will be taken to its overview page.
1. In the **Manage** section of the left menu, select **Single sign-on**.
2. On the "Select a single sign-on method" page, choose the **SAML** tile. This will open the SSO configuration page.
3. Scroll down to the **SAML Certificates** section and click **Download** next to the **Federation Metadata XML** button.
4. Go to the Atonom **[Identity Management](https://app.getsignals.ai/#/v2/settings/saml)** page and check "Upload XML Directly" then paste the contents of the **Federation Metadata XML** file into the text area labelled **Metadata XML**.
#### **A. Basic SAML Configuration**
These settings define where Atonom sends and receives SAML messages.
1. In the **Basic SAML Configuration** section, select the **Edit** (pencil) icon.
2. Configure the following fields using values from Atonom **[Identity Management](https://app.getsignals.ai/#/v2/settings/saml)** page:
* **Identifier (Entity ID)**: Click **Add identifier** and enter the `Entity ID / Issuer` value from Atonom **[Identity Management](https://app.getsignals.ai/#/v2/settings/saml)** page.
* **Reply URL (Assertion Consumer Service URL)**: Click **Add reply URL** and enter the `Assertion Consumer Service (ACS) URL`.
* **Sign on URL**: Enter the `Atonom SAML Login URL` value.
3. Select **Save** at the top of the pane.
#### **B. SAML Certificates**
Atonom automatically downloads and validates your Entra ID signing certificate from the federation metadata endpoint. No manual certificate upload is required on the Atonom side.
1. In the **SAML Certificates** section, ensure there is an active certificate
2. Note the certificate details for troubleshooting purposes if needed
#### **C. Configure User Attributes & Claims (Required)**
⚠️ **Important**: The attribute names must match exactly what Atonom expects or authentication will fail.
1. In the **Attributes & Claims** section, select the **Edit** (pencil) icon.
2. The `Unique User Identifier (Name ID)` should be set to `user.userprincipalname` by default, which is sufficient.
3. Ensure the following **Additional claims** exist with these exact names. If not, select **+ Add new claim** to create them:
* **Name:** `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | **Source:** `Attribute` | **Source attribute:** `user.mail`
* **Name:** `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | **Source:** `Attribute` | **Source attribute:** `user.givenname`
* **Name:** `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | **Source:** `Attribute` | **Source attribute:** `user.surname`
4. Select **Save**.
***
### **4. Configure Atonom Environment**
#### **Calendar Access Security Group (Optional)**
If you want to restrict who can connect calendars, create a dedicated security group in your Entra tenant and use that group's ID in Atonom.
1. In Microsoft Entra ID, create a new **Security group** for calendar access.
2. After the group is created, copy the group's **Object ID**.
3. Ensure the Atonom Entra app is given access to `user.groups` so Atonom can evaluate group membership.
4. In Atonom's **Identity Management** page, paste that group ID into the **Calendar Access** input.
Only users assigned to that Entra security group will be able to connect their calendar to Atonom.
Already signed-in users will need to re-authenticate for their roles to be considered.
***
### **5. Assign Users and Groups**
By default, no one in your organization can use the new application. You must assign specific users or user groups who should have access to Atonom.
1. Navigate to your **Atonom** enterprise application in Entra ID.
2. In the **Manage** section of the left menu, select **Users and groups**.
3. Select **+ Add user/group**.
4. Under **Users**, click "None Selected" and choose the appropriate users or groups from the list.
5. Click **Select** and then **Assign**.
⚠️ **Important**: Users must have pending invites in the Atonom system to successfully log in via SAML. See the [User Invitation Guide](/SAML/invite-users) for details on inviting users to Atonom.
***
### **6. Test Single Sign-On**
After configuration is complete and you have assigned users:
1. On the Identity Management page, copy the **Atonom SAML Login URL** and paste it into a new tab.
2. Follow the prompts.
3. If you have an invite pending to the email you've signed in with, and that email is assigned to the active directory, you should be redirected to the Atonom new user onboarding.
***
### **7. Available SAML Endpoints**
For reference, you can always check Atonom SAML endpoints in the **[Identity Management](https://app.getsignals.ai/#/v2/settings/saml)** page.
***
### **8. Troubleshooting**
If you encounter issues, check these common configuration problems:
* **User Cannot Log In (Error `AADSTS50105`)**: This error means the user trying to sign in has not been assigned to the application. Follow the steps in the **Assign Users and Groups** section to grant them access.
* **"No pending invite found" Error**: Users must have a pending invite in the Atonom system. See the [User Invitation Guide](/SAML/invite-users) for details on inviting users to Atonom.
* **Claim Mapping Errors**: Verify that the user attribute claims in step 3C use the exact URIs specified. Incorrect claim names will cause authentication failures.
* **Entity ID Mismatch**: Ensure the **Identifier (Entity ID)** in Entra ID exactly matches the `entityID` from your Atonom metadata endpoint.
* **Redirect URI Mismatch**: Ensure the **Reply URL** in Entra ID exactly matches the `AssertionConsumerService` location from your Atonom metadata.
* **Certificate Validation Errors**: Atonom automatically downloads your Entra ID certificate. If issues persist, check that your Entra ID certificate is active and valid.
* **Logout Issues**: Verify the **Logout URL** matches the `SingleLogoutService` location from your Atonom metadata.
* **Session Management**: Atonom uses Redis for session storage. Logout requests will invalidate both the SAML session and the application session cookie.
***
### **9. Security Notes**
* Atonom validates SAML assertions using your Entra ID's signing certificate
* All SAML requests from Atonom are signed for security
# Introduction
Source: https://docs.atonom.ai/SAML/introduction
Introduction to SAML single sign-on (SSO) integration with Atonom
Welcome to the Atonom SAML (Security Assertion Markup Language) integration guide. This section provides comprehensive documentation for setting up and managing SAML-based single sign-on (SSO) with the Atonom platform.
***
### **What is SAML?**
SAML (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between parties. In the context of Atonom, SAML enables:
* **Single Sign-On (SSO)**: Users can access Atonom using their existing organizational credentials
* **Centralized Identity Management**: Manage user access through your existing identity provider
* **Enhanced Security**: Leverage your organization's security policies and multi-factor authentication
* **Simplified User Experience**: Seamless login without additional passwords to remember
***
### **How SAML Works with Atonom**
The SAML integration follows a standard flow:
1. **User initiates login** to Atonom
2. **Atonom redirects** the user to your identity provider (e.g., Microsoft Entra ID)
3. **User authenticates** with your identity provider
4. **Identity provider sends** a SAML assertion back to Atonom
5. **Atonom validates** the assertion and grants access to the authenticated user
```mermaid theme={null}
sequenceDiagram
participant User
participant Atonom
participant EntraID as Microsoft Entra ID
User->>Atonom: 1. Initiate Login
Atonom->>EntraID: 2. Redirect to IdP
User->>EntraID: 3. Authenticate
EntraID->>Atonom: 4. SAML Assertion
Atonom->>User: 5. Grant Access
```
***
### **Supported Identity Providers**
Atonom currently supports SAML integration with:
* **Microsoft Entra ID** (formerly Azure AD) - Full documentation available
* **Okta** - Contact support for configuration details
* **OneLogin** - Contact support for configuration details
* **ADFS** - Contact support for configuration details
* **Custom SAML 2.0 Providers** - Contact support for compatibility verification
***
### **Prerequisites**
Before setting up SAML integration, ensure you have:
#### **On the Identity Provider Side**
* Administrative access to your identity provider
* Ability to create and configure enterprise applications
* Permission to assign users to applications
* Understanding of your organization's user management policies
#### **On the Atonom Side**
* Administrative access to your Atonom account
* Understanding of your desired user roles and permissions
* Access to invite and manage users in the platform
***
### **SAML Configuration Overview**
Setting up SAML with Atonom involves several key steps:
1. **Configure your Identity Provider**
* Create a new enterprise application for Atonom
* Configure SAML settings and certificates
* Set up user attributes and claims
* Assign users to the application
2. **Configure Atonom**
* Obtain service provider metadata
* Configure environment variables
* Test the SAML integration
3. **User Management**
* Invite users to the Atonom platform
* Assign appropriate roles and permissions
* Test user login flow
***
### **Security Features**
Atonom SAML integration includes robust security features:
#### **Assertion Validation**
* **Digital Signature Verification**: All SAML assertions are validated using your IdP's signing certificate
* **Timestamp Validation**: Assertions are checked for validity periods to prevent replay attacks
* **Audience Restriction**: Assertions are validated to ensure they're intended for Atonom
#### **Session Management**
* **Secure Session Storage**: User sessions are stored securely in Redis
* **HTTP-Only Cookies**: Session cookies are protected from client-side script access
* **Proper Logout**: Both IdP and application sessions are terminated during logout
#### **Data Protection**
* **Encrypted Communication**: All SAML exchanges use HTTPS encryption
* **Minimal Data Collection**: Only necessary user attributes are processed
* **Audit Logging**: Authentication events are logged for security monitoring
***
### **User Attributes and Claims**
Atonom requires specific user attributes to function properly:
| Attribute | SAML Claim URI | Source | Required |
| ------------------- | -------------------------------------------------------------------- | ------------------------ | -------- |
| Email | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` | ✅ Yes |
| First Name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` | ✅ Yes |
| Last Name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` | ✅ Yes |
| User Principal Name | Name ID | `user.userprincipalname` | ✅ Yes |
***
### **Getting Started**
Ready to set up SAML with Atonom? Follow these steps:
1. **Choose your identity provider** from our supported list
2. **Review the specific integration guide** for your provider
3. **Gather necessary information** such as metadata URLs and certificates
4. **Follow the step-by-step configuration** instructions
5. **Test the integration** with a pilot group of users
6. **Roll out to your organization** once testing is complete
***
### **Support and Resources**
#### **Documentation**
* [Microsoft Entra ID Integration](/SAML/entra) - Complete setup guide
* [User Invitation Process](/SAML/invite-users) - Managing user access
#### **API Endpoints**
For reference, Atonom provides these SAML endpoints:
* **Metadata**: `https://app.getsignals.ai/api/core/auth/azure/saml/metadata`
* **Login**: `https://app.getsignals.ai/api/core/auth/azure/saml/login`
* **Callback**: `https://app.getsignals.ai/api/core/auth/azure/saml/callback`
* **Logout**: `https://app.getsignals.ai/api/core/auth/azure/saml/logout`
#### **Getting Help**
* **Technical Support**: Contact your Atonom support team for integration assistance
* **Documentation Issues**: Report any documentation problems or suggestions
* **Feature Requests**: Submit requests for additional identity provider support
***
### **Next Steps**
Choose your integration path:
Complete guide for configuring SAML with Microsoft Entra ID
Learn how to invite and manage users for SAML authentication
For other identity providers or custom configurations, please contact our support team for assistance.
# Inviting Users to Atonom
Source: https://docs.atonom.ai/SAML/invite-users
How to invite and manage users in the Atonom platform for SAML authentication
This guide explains how to invite users to the Atonom platform so they can authenticate via SAML single sign-on (SSO).
***
### **Prerequisites**
Before inviting users, ensure that:
* You are logged into the Atonom platform as an Administrator.
* You have the email address of the user you'd like to invite.
***
### **1. Understanding User Invitation Flow**
For SAML authentication to work properly, users must have pending invitations in the Atonom system before they attempt to log in. This process ensures security and proper user provisioning within the Atonom platform.
⚠️ **Important**: Users will encounter a "No pending invite found" error if they try to log in via SAML without a pending invitation in Atonom.
📋 **Note**: After inviting users in Atonom, administrators must also assign them to the Atonom enterprise application in Microsoft Entra ID. See the [Entra Integration Guide](/SAML/entra) for details on user assignment in Entra ID.
***
### **2. Inviting Users in Atonom**
#### **Step 1: Access User Management**
1. Log into your Atonom dashboard at `https://app.getsignals.ai`
2. Navigate to `https://app.getsignals.ai/#/user_management/users`
3. Look for **Invite User** in the top right.
#### **Step 2: Send Invitations**
1. Click **Invite User**
2. Enter the user's email address (this must match their Entra ID email)
3. Select the desired role/permissions for the user
4. Select the desired chat permissions for the user
5. Click **Send Invite**
#### **Step 3: Verify Invitation Status**
* The user will appear in your user list with a **Pending** status
* The invitation email is sent to the user's email address
* Keep track of pending invitations for SAML assignment
***
### **3. User Login Process**
Once users have been invited in Atonom and assigned in Entra ID, they can log in via SAML:
#### **Option 1: Direct SAML Login**
Users can navigate directly to: `https://app.getsignals.ai/api/core/auth/azure/saml/login`
***
### **4. Troubleshooting User Invitations**
#### **Common Issues and Solutions**
**"No pending invite found" Error**
* Verify the user has a pending invitation in Atonom
* Check that the email address matches exactly between Atonom and Entra ID
* Ensure the invitation hasn't expired
* Confirm the user has been assigned to the Atonom application in Entra ID (see [Entra Integration Guide](/SAML/entra))
**User Cannot Access After Login**
* Verify the user's role and permissions in Atonom
* Check if additional onboarding steps are required
* Confirm the user is assigned to the correct groups/resources
**Invitation Email Not Received**
* Check spam/junk folders
* Verify the email address is correct
* Resend the invitation if necessary
* Contact your email administrator about delivery issues
**User Shows as "Pending" Indefinitely**
* The user may not have completed the invitation process
* Check if they've clicked the invitation link
* Verify they can access the SAML login flow
***
### **5. Next Steps**
After successfully inviting and configuring users:
1. **Test the complete flow** with a test user
2. **Plan regular reviews** of user access and roles
For additional support with user management, contact Atonom directly.
# Okta Integration for Atonom
Source: https://docs.atonom.ai/SAML/okta
Setting up SAML single sign-on (SSO) for the Atonom application using Okta as your identity provider.
This guide will walk you through the process of configuring SAML-based single sign-on (SSO) for the Atonom application within your Okta tenant. This process involves creating a new SAML application, configuring the necessary SAML parameters, and assigning users.
***
### **1. Create the SAML Application**
Since Atonom is not yet in the Okta Integration Network, you will need to create a new custom SAML application.
1. Sign in to your **Okta Admin Console**.
2. Navigate to **Applications** in the main menu.
3. Click **Create App Integration**.
4. Select **SAML 2.0** as the sign-in method.
5. Click **Next** to proceed to the configuration.
6. In the **General Settings** tab, fill out the form and click **Next**:
7. In the **Atonom** application, go to the bottom left and click on your profile picture. Click settings, Org Settings, Identity Management. **(This is placeholder text with no images until we have finalized the settings page ports)**.
8. Once there, copy the **Assertion Consumer Service (ACS) URL** and paste it into the **Single sign-on URL** field in the **General Settings** tab in Okta.
9. Next, copy the **Entity ID / Issuer** from the **Atonom** app and paste it into the **Audience URI (SP Entity ID)** field in the **General Settings** tab in Okta.
10. On **Okta**, for **Name ID Format**, select `Unspecified`. This uses Okta's default.
11. For **Application username**, select `Email`.
12. Scroll down and click **Next**.
13. Now, check **Contact App Vendor** and click **Finish**.
14. After clicking **Finish**, you will be redirected to the **Atonom** application in Okta. Copy the **Metadata URL** as shown below.
15. Now, go back to the **Atonom** application Identity Management page and paste the **Metadata URL** into the **Metadata URL** field.
***
# Book Meeting
Source: https://docs.atonom.ai/api-reference/calendarservice/book-meeting
/api-reference/connectors/openapi.yaml post /v1/calendar/book-meeting
# Cancel Meeting
Source: https://docs.atonom.ai/api-reference/calendarservice/cancel-meeting
/api-reference/connectors/openapi.yaml post /v1/calendar/cancel-meeting
# Get Available Times
Source: https://docs.atonom.ai/api-reference/calendarservice/get-available-times
/api-reference/connectors/openapi.yaml post /v1/calendar/get-available-times
# List Calendars
Source: https://docs.atonom.ai/api-reference/calendarservice/list-calendars
/api-reference/connectors/openapi.yaml post /v1/calendar/list-calendars
# Post v1calendarcreate event
Source: https://docs.atonom.ai/api-reference/calendarservice/post-v1calendarcreate-event
/api-reference/connectors/openapi.yaml post /v1/calendar/create-event
# Post v1calendarlist events
Source: https://docs.atonom.ai/api-reference/calendarservice/post-v1calendarlist-events
/api-reference/connectors/openapi.yaml post /v1/calendar/list-events
# Post v1calendarupdate meeting
Source: https://docs.atonom.ai/api-reference/calendarservice/post-v1calendarupdate-meeting
/api-reference/connectors/openapi.yaml post /v1/calendar/update-meeting
# Verify Calendar Connection
Source: https://docs.atonom.ai/api-reference/calendarservice/verify-calendar-connection
/api-reference/connectors/openapi.yaml post /v1/calendar/verify-calendar-connection
# Introduction
Source: https://docs.atonom.ai/api-reference/connectors/integration_connectors
Request and response schemas for endpoints your server exposes when Atonom invokes connector actions.
See [Integration Connectors](/integrations/integration_connectors) for an overview and how to create a connector in the Atonom app.
## How this differs from the API Reference tab
The **API Reference** tab documents endpoints **you call on Atonom** — for example scheduling a meeting or creating a contact. Those requests go to Atonom with your API credentials.
This **Integration Connectors** tab documents the opposite direction: endpoints **your server must implement** so Atonom can invoke connector actions you configure in the dashboard. Atonom calls **your** infrastructure when a Cloud Employee or workflow triggers an action.
## About this reference
The operations listed here are **not live Atonom-hosted URLs**. They document an **illustrative contract**: the kinds of HTTP (and, where applicable, gRPC) handlers **your** infrastructure should implement. Path names and base URLs in the spec exist to show shape and semantics, not to point at a service you can call as-is.
## Generating implementation code
You can and should **generate** clients, servers, types, or validators from the Integration Connectors OpenAPI definition [openapi.yaml](/api-reference/connectors/openapi.yaml) using your preferred toolchain (for example OpenAPI Generator, `openapi-typescript`, or protoc plugins where gRPC is involved). That keeps your implementation aligned with the documented request and response models and reduces drift as the contract evolves.
## Errors that should be stored as logs
When a connector action fails in a way that should appear in Atonom **logs** (as opposed to only a generic failure), use one of the following patterns:
* **gRPC** — Return a normal gRPC error status on the RPC. Atonom can treat that as a loggable failure path when you follow the connector contract for your action.
* **HTTP** — Return a response that includes the error. Put a short, operator-safe explanation in the header value.
**Do not include PII** (Personally identifiable information, names, emails, phone numbers, account identifiers, free-form user content, tokens, or other sensitive data); use internal codes or generic descriptions instead so logs stay safe for broad access.
For standard request validation or transport errors, follow normal HTTP status codes and bodies as described in the OpenAPI document.
# Get Account
Source: https://docs.atonom.ai/api-reference/crmservice/get-account
/api-reference/connectors/openapi.yaml post /v1/crm/get-account
# Get Inventory Item By Serial
Source: https://docs.atonom.ai/api-reference/inventoryservice/get-inventory-item-by-serial
/api-reference/connectors/openapi.yaml post /v1/inventory/get-by-serial
# Get Estimated Wait Time
Source: https://docs.atonom.ai/api-reference/routingservice/get-estimated-wait-time
/api-reference/connectors/openapi.yaml post /v1/routing/estimated-wait-time
# Get Routing Entities
Source: https://docs.atonom.ai/api-reference/routingservice/get-routing-entities
/api-reference/connectors/openapi.yaml post /v1/routing/get-routing-entities
# Get Routing Policies
Source: https://docs.atonom.ai/api-reference/routingservice/get-routing-policies
/api-reference/connectors/openapi.yaml post /v1/routing/get-routing-policies
# Route Agent
Source: https://docs.atonom.ai/api-reference/routingservice/route-agent
/api-reference/connectors/openapi.yaml post /v1/routing/route-agent
# Create Ticket
Source: https://docs.atonom.ai/api-reference/ticketsservice/create-ticket
/api-reference/connectors/openapi.yaml post /v1/tickets/create-ticket
# Get Ticket
Source: https://docs.atonom.ai/api-reference/ticketsservice/get-ticket
/api-reference/connectors/openapi.yaml post /v1/tickets/get-ticket
# Update Ticket
Source: https://docs.atonom.ai/api-reference/ticketsservice/update-ticket
/api-reference/connectors/openapi.yaml post /v1/tickets/update-ticket
# Introduction
Source: https://docs.atonom.ai/get-started/index
## Welcome to Atonom - The always-on AI workforce
## Cloud Employees DNA - Trained on over 1 billion conversations
Unlike traditional tools and AI agents that require tedious customization and constant oversight, Atonom's Cloud Employees combine buyer signal data, pre-trained insights from more than a billion conversations and real-time context from CRM, ERP, marketing, e-commerce, review and social platforms that make the Cloud Employees intelligent and continuously adapting to drive measurable business outcomes.
## Quick Actions
Let our Cloud Employee help you schedule your next meeting
Initiate a phone call with our Cloud Employee
Add or update contact information in your system
Handle incoming calls with our Cloud Employee
## Multi-Channel Engagement
Cloud Employees operate seamlessly across phone, email, chat, and SMS so they understand what a positive conversation is and deliver immediate value. They're available 24/7 to help you scale your operations and drive better business outcomes.
Get started with Atonom Cloud Employees
Explore our 100+ tool integrations
# Build Your First Cloud Employee
Source: https://docs.atonom.ai/get-started/quickstart
Learn how to create and configure a Cloud Employee in Atonom.
## Getting Started
Login to your Atonom account and follow along to create and configure your first Cloud Employee
## Step-by-Step Guide
### 1. Access Cloud Employees
1. Log in to your Atonom account
2. Click on the "Cloud Employees" tab in the left sidebar
### 2. Create New Employee
1. Click "Add New Employee" in the top right corner
2. This will take you to the Employee Onboarding page
### 3. Select Employee Type
Choose from the following employee types:
* Chat
* Voice
* Inbound Calling
* Outbound Calling
### 4. Choose Objective
Select the primary objective for your Cloud Employee based on your needs.
### 5. Configure Basic Settings
Customize your Cloud Employee's basic settings to match your requirements.
### 6. Set Up Profile
In the Profile section, configure:
* Employee name
* Role
* Department
* Voice preview (for voice-enabled employees)
### 7. Customize Appearance
1. Click the pencil icon in the top right corner of the employee's image
2. Upload or select a new image for your Cloud Employee
### 8. Define Employee Identity
In the employee identity box, specify:
* Tasks the employee should complete
* Context the employee should know
* Key responsibilities
### 9. Configure Style Guide
Set your employee's:
* Main traits
* Communication guidelines
* Response patterns
### 10. Set Welcome Message
In the Welcome Message box:
* Create an opening message
* Configure response options for visitors
### 11. Create Talk Tracks
In the talk tracks box:
* Create step-by-step response guides
* Tailor messages to your specific needs
### 12. Add Example Conversations
In the example conversations box:
* Provide sample interactions
* Illustrate desired communication style
### 13. Configure Data Capture
In the data capture field (top right):
* Select what data to capture during conversations
* Configure data collection preferences
### 14. Create Custom Fields
1. Click "Create" in the Data Capture section
2. Add custom fields to collect specific information
3. Fields will automatically collect and store relevant data
### 15. Add Capabilities
On the right side of the settings page, enable features like:
* Teammate notifications
* Meeting booking
* Additional integrations
### 16. Connect Knowledge Base
1. Select a previously created knowledge base
2. This provides additional information to your employee
3. For help creating a knowledge base, see the knowledge base documentation
### 17. Adjust Sentiment
In the sentiment section:
* Modify the temperature setting
* Control the tone of responses
### 18. Configure Webhook
In the Webhook URL section (bottom right):
* Add your webhook URL
* Configure data transmission settings
### 19. Activate Employee
1. Find the active switch at the top right
2. Toggle to activate (green indicates active status)
### 20. Test Your Employee
1. Click "Role Play" at the top right
2. Test the employee's responses and behavior
### 21. Save Changes
Click the save option at the top right to preserve your configuration.
Remember to test your Cloud Employee thoroughly before deploying it to production. Use the Role Play feature to ensure it responds appropriately to various scenarios.
## Next Steps
Visit the API Reference section to learn how to use the Atonom API to integrate your Cloud Employee with your existing systems
# Calendar
Source: https://docs.atonom.ai/integrations/calendar
OAuth scopes and permissions for Google Calendar and Microsoft Calendar (Outlook) when connecting calendars to Atonom.
Atonom supports **calendar integrations** for Google Calendar and Microsoft Calendar (Outlook / Office 365) using user-delegated OAuth tokens. These integrations power meeting scheduling features such as availability lookup, booking, updating, and canceling events.
For step-by-step instructions on connecting and configuring your calendar after OAuth, see [Calendar Setup](/integrations/calendar-setup). For meeting types and booking templates, see [Meeting Types](/integrations/meeting-types).
Users connect a calendar from **My Settings → My Calendar** in the Atonom app. During OAuth, each provider prompts the user to grant the scopes listed below.
Calendar connection is per-user. Each user authorizes their own mailbox and calendar access. All permissions are **delegated** — Atonom acts on behalf of the signed-in user, not at the application/tenant-wide level. Tenant admins can optionally restrict who may connect a Microsoft calendar using an Entra security group — see the [Entra Integration guide](/SAML/entra#calendar-access-security-group-optional).
## Google Calendar
Atonom requests the following scopes when a user connects Google Calendar:
| Scope | Description | Used by Atonom for |
| ---------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `https://www.googleapis.com/auth/calendar.events` | View and edit events on all calendars the user can access | Reading busy times and creating/updating/deleting meeting events |
| `https://www.googleapis.com/auth/calendar.calendarlist.readonly` | See the list of Google calendars the user is subscribed to | Listing calendars for the calendar picker and resolving the primary calendar during connection verification |
| `https://www.googleapis.com/auth/userinfo.email` | View the user's email address | Identifying the connected mailbox during connection verification |
### Admin notes (Google Cloud)
If your organization manages its own Google OAuth client for Atonom:
1. Create or use a Google Cloud OAuth 2.0 client (Web application type).
2. Enable the **Google Calendar API** for the project.
3. If your Google Workspace admin restricts third-party app access, allowlist the Atonom OAuth client for the scopes above.
***
## Microsoft Calendar (Outlook / Office 365)
Atonom requests the following Microsoft Graph **delegated** scopes when a user connects Microsoft Calendar:
| Scope | Description | Used by Atonom for |
| --------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `offline_access` | Maintain access to data the user has granted; receive refresh tokens | Long-lived calendar connections without requiring the user to sign in again |
| `https://graph.microsoft.com/User.Read` | Sign in and read the signed-in user's profile | Resolving the connected user's mailbox address |
| `https://graph.microsoft.com/Calendars.ReadWrite` | Read and write events in the user's calendars | Listing calendars, reading busy times, and creating/updating/deleting meeting events on calendars the user owns |
| `https://graph.microsoft.com/Calendars.Read.Shared` | Read events in calendars shared with the user | Reading busy times on **shared or delegated calendars** when the user selects them in calendar settings |
**`Calendars.Read.Shared` is required for shared calendars.** If a user selects a calendar that was shared with them (rather than one they own), availability checks against that calendar require this scope. Without it, operations on the user's own calendars may still work, but shared-calendar selection can fail.
### Admin notes (Microsoft Entra)
If your organization manages its own Entra app registration for Atonom calendar access:
1. Register a multi-tenant application (or single-tenant, if your deployment uses a specific tenant ID).
2. Add the delegated Graph permissions matching the scopes above.
3. Grant **admin consent** in your tenant if your policy requires it for those permissions.
4. Optionally restrict which users may connect calendars using an Entra security group — see [Calendar Access Security Group](/SAML/entra#calendar-access-security-group-optional) in the Entra integration guide.
***
## Scope summary
| Provider | Scopes requested |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Google Calendar** | `https://www.googleapis.com/auth/calendar.events`, `https://www.googleapis.com/auth/calendar.calendarlist.readonly`, `https://www.googleapis.com/auth/userinfo.email` |
| **Microsoft Calendar** | `offline_access`, `User.Read`, `Calendars.ReadWrite`, `Calendars.Read.Shared` |
## Disconnecting
Users can disconnect their calendar from **My Settings → My Calendar**. Disconnecting removes stored OAuth tokens for that provider from Atonom; it does not revoke the app in Google or Microsoft. Users who want to fully revoke access can do so from their [Google Account permissions](https://myaccount.google.com/permissions) or [Microsoft account app permissions](https://account.live.com/consent/Manage) pages.
## Need help?
If users see authorization errors, missing calendars, or shared-calendar failures:
* Confirm the OAuth client in Google Cloud or Entra includes the scopes in this document.
* For Microsoft shared calendars, verify `Calendars.Read.Shared` is granted.
* For Microsoft tenants with conditional access or consent policies, ensure the Atonom app is allowed and admin consent has been granted where required.
Contact [support@atonom.ai](mailto:support@atonom.ai) if you need assistance.
# Calendar Setup
Source: https://docs.atonom.ai/integrations/calendar-setup
Connect Google or Microsoft Calendar and configure meeting and availability settings in Atonom.
Connect your Google or Microsoft calendar in Atonom to enable meeting scheduling. After OAuth, configure **Meeting Settings** and **Availability Settings** so Atonom can find open times and book meetings on your calendar—for Cloud Employees, the API, and other booking flows.
For OAuth scopes, admin setup, and permission details, see [OAuth & Permissions](/integrations/calendar). For creating meeting types and how they work with booking, see [Meeting Types](/integrations/meeting-types). Microsoft tenants can optionally restrict who may connect a calendar using an [Entra security group](/SAML/entra#calendar-access-security-group-optional).
## Overview
Open **My Settings → My Calendar** in the Atonom app ([`/#/v2/my_settings/my_calendar`](https://app.getsignals.ai/#/v2/my_settings/my_calendar)).
From there you will:
1. Connect Google or Microsoft via OAuth
2. Configure meeting preferences (links, buffer time, lead time)
3. Set availability (timezone, selected calendars, weekly hours)
That is all that is required for meeting booking through Cloud Employees, the API, and other Atonom flows. Optionally, you can also enable self-service booking on your **profile page** (see below).
```mermaid theme={null}
flowchart LR
connect[ConnectCalendar] --> meeting[MeetingSettings]
meeting --> availability[AvailabilitySettings]
availability --> optionalProfile["ProfilePageBooking optional"]
```
***
## Connect your calendar
1. Go to **My Settings → My Calendar**
2. On the **Calendar Connection** card, choose **Microsoft** or **Google**
3. Complete the OAuth sign-in and grant the requested permissions
4. You are redirected back to **My Calendar**, where **Meeting Settings** and **Availability Settings** appear
Calendar connection is per-user. Each person authorizes their own mailbox and calendar access.
On first connect, Atonom applies these defaults:
| Setting | Default |
| ------------------ | --------------------------------------------------------- |
| Weekly hours | Monday–Friday, 9:00 AM–5:00 PM |
| Timezone | Your company's chat timezone (falls back to UTC if unset) |
| Selected calendars | **All** calendars on the connected account |
You can change all of these in **Availability Settings** after connecting.
To remove a connection, use **Disconnect Calendar** at the top of the My Calendar page. This removes stored OAuth tokens from Atonom but does not revoke the app in Google or Microsoft.
***
## Post-connection setup checklist
Complete these steps after connecting your calendar:
1. Configure **Meeting Settings** and click **Save Settings**
2. Review **Availability Settings** (timezone, selected calendars, weekly hours) — changes save automatically
Enabling **Allow visitors to book a meeting with me** on **My Profile** is optional. It only controls self-service booking on your public profile page and is not required for Cloud Employees, the Schedule a Meeting API, or other booking flows.
***
## Meeting Settings
The **Meeting Settings** card controls how booked meetings behave and what information is included in invitations.
| Setting | Purpose |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Personal Meeting Link** | Zoom, Teams, or other URL included in booked calendar invites |
| **Email Signature** | Text appended to meeting-related emails |
| **Meet Now Link** | Link you can drop into live chats to start a meeting with a visitor immediately |
| **Same as personal meeting link** | Copies your personal meeting link into the Meet Now field |
| **Buffer Time** | Minimum gap after a meeting ends before another can be scheduled (15 minutes–2 hours, or none) |
| **Lead Time** | Your personal minimum notice before a slot can be booked (15 minutes–48 hours, or none) |
Meeting settings do **not** auto-save. Click **Save Settings** after making changes.
Direct calendar integrations support two conferencing options on **My Calendar → Meeting Settings**:
* **Auto-generate links (recommended)** — creates native **Google Meet** or **Microsoft Teams** join links based on your connected calendar.
* **Use personal meeting link** — paste a Zoom, Teams, or other URL; it is included on booked calendar invites.
Zoom and GoToMeeting auto-generation on direct calendar is not supported; use a personal link for those providers.
### Buffer and lead time options
**Buffer time:** No buffer, 15 min, 30 min, 45 min, 1 hour, 1 hr 15 min, 1 hr 30 min, 1 hr 45 min, 2 hours
**Lead time:** No lead time, 15 min, 30 min, 45 min, 1 hour, 1 hr 30 min, 2 hours, 3 hours, 4 hours, 5 hours, 6 hours, 7 hours, 8 hours, 12 hours, 24 hours, 48 hours
### How lead time is applied
Each **meeting type** in Atonom can also have its own lead time configured by an admin. When availability is calculated for a booking, Atonom uses the **longer** of the two values:
* **Personal lead time** from your Meeting Settings
* **Lead time** configured on the meeting type being booked
For example, if your personal lead time is 15 minutes but the meeting type requires 2 hours, visitors cannot book a slot starting within the next 2 hours. If your personal lead time is 24 hours but the meeting type requires 1 hour, the 24-hour personal setting applies.
This applies across booking flows—profile pages, Cloud Employees, chat, and the API—whenever a specific meeting type is used. See [Meeting Types](/integrations/meeting-types#scheduling-rules-at-book-time) for the full list of rules applied at book time.
***
## Availability Settings
The **Availability Settings** card defines when you are bookable and which calendars Atonom checks for conflicts.
| Setting | Purpose | Save behavior |
| ---------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| **Timezone** | Used when evaluating your weekly availability windows | Auto-save on change |
| **Selected Calendars** | Calendars checked for busy times; bookings are created on the selected calendar(s) | Auto-save on change |
| **Weekly hours** | Bookable time windows for each day of the week | Auto-save (debounced) |
Changes to availability settings save automatically. A brief **Saving...** indicator appears while updates are in progress.
### Timezone
Select the IANA timezone used to interpret your weekly hours grid (for example, `America/New_York` or `Europe/London`). Your painted availability windows are evaluated in this timezone.
### Selected calendars
After connecting, Atonom loads the calendars available on your Google or Microsoft account. Use the multiselect to choose which calendars to include.
* Select **All** to check every calendar on the account (default on first connect)
* Select individual calendars to limit availability checks and booking targets
**Shared Microsoft calendars** require the `Calendars.Read.Shared` scope. If a user selects a calendar shared with them (rather than one they own), availability checks can fail without this permission. See [OAuth & Permissions](/integrations/calendar#microsoft-calendar-outlook--office-365) for details.
If calendars fail to load, try reconnecting your account or confirm the OAuth scopes in the permissions guide.
### Weekly hours
Use the weekly hours grid to paint when you are available for meetings:
* **Click** or **click and drag** to mark 30-minute slots as available
* Scroll the grid for early-morning or late-night hours (full 24-hour day in 30-minute steps)
* Defaults to Monday–Friday, 9:00 AM–5:00 PM until you change them
***
## Profile page meeting booking (optional)
A **profile page** is a public page for an individual team member in your organization. Each user can have their own profile page with a shareable link, showing their name, photo, company branding, and optional actions such as **Chat with me** or meeting booking.
Profile pages are separate from Cloud Employee conversations. Visitors who open a profile page link interact directly with that person's page—not with a Cloud Employee.
### Allow visitors to book a meeting with me
If you want visitors to schedule meetings from your profile page:
1. Go to **My Settings → My Profile**
2. Enable **Enable my public profile page** (if not already on)
3. Enable **Allow visitors to book a meeting with me**
4. Configure which meeting types appear on your profile under **Agent Page Meetings** — see [Meeting Types](/integrations/meeting-types#profile-pages-and-meeting-types)
This toggle is disabled until a calendar is connected. When enabled, visitors who open your profile page link can pick a meeting type and book a time from your availability.
This setting applies **only** to booking on your profile page. It does not enable or disable other meeting booking flows, including:
* Cloud Employees with the meeting booking capability
* The [Schedule a Meeting API](/api-reference/schedule-meeting/create)
* Meetings booked on behalf of a user during live chat or voice conversations
You can connect your calendar and configure meeting/availability settings without turning this on. Leave it disabled if you do not want self-service booking on your public profile page.
***
## Troubleshooting
| Issue | What to check |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization errors during connect | OAuth client scopes and admin consent — see [OAuth & Permissions](/integrations/calendar) |
| Calendars not loading in the picker | Reconnect the calendar; verify Google Calendar API or Microsoft Graph permissions are granted |
| Shared calendar availability fails | Confirm `Calendars.Read.Shared` is granted for Microsoft accounts |
| Bookings fail or missing meeting links | Save **Meeting Settings** with a valid personal meeting link; confirm the target calendar is selected |
| Wrong available times shown | Verify **Timezone** and **Weekly hours** match your intended schedule |
| User cannot connect (Microsoft) | Tenant may restrict calendar access via an Entra security group — see [Calendar Access Security Group](/SAML/entra#calendar-access-security-group-optional) |
Contact [support@atonom.ai](mailto:support@atonom.ai) if you need assistance.
***
## What's next
Create meeting types and configure how they work with calendar booking
Google and Microsoft scopes, admin setup, and disconnect behavior
Book meetings programmatically via the Atonom API
Enable the meeting booking capability on a Cloud Employee
# Gorgias Integration for Atonom
Source: https://docs.atonom.ai/integrations/gorgias
Setting up integration between Atonom and Gorgias for seamless customer support workflows.
This guide will walk you through the simple process of integrating Atonom with Gorgias to enhance your customer support capabilities.
***
### **Step 1: Find Atonom in Gorgias App Store**
1. Log into your Gorgias account
2. Navigate to **Settings > App Store**
3. Search for "Atonom" in the app store
4. Click on the **Atonom** app to view its details
***
### **Step 2: Connect Atonom**
1. On the Atonom App page, click the **Connect Atonom** button
2. This will redirect you to the Atonom application
***
### **Step 3: Sign In to Atonom**
1. If you're not already signed in to Atonom, you'll be prompted to sign in
2. Enter your Atonom account credentials
3. Complete the sign-in process
***
### **Step 4: Authorize the Integration**
1. After signing in, you'll be taken to an authorization page
2. Review the integration details and permissions
3. Click **Authorize** to connect your Atonom account with Gorgias
***
### **Step 5: Accept Permissions in Gorgias**
1. You'll be redirected back to Gorgias
2. Review the scopes and permissions that Atonom is requesting
3. Click **Accept** to grant the necessary permissions
4. The integration is now complete!
***
### **What's Next?**
Once the integration is set up, you can:
* Set up Cloud Employees to handle incoming tickets
* Create tickets from Atonom conversations
### **Need Help?**
If you encounter any issues during the setup process:
* Check that you have admin access to your Gorgias account
* Ensure you have an active Atonom account
* Contact support if you need assistance with the integration
# Integration Connectors
Source: https://docs.atonom.ai/integrations/integration_connectors
Build custom connectors that connect your servers to Atonom Cloud Employees and other product flows.
## Overview
Integration connectors let your organization extend Atonom without waiting on a first-party integration. You define how Atonom calls **your** infrastructure so Cloud Employees, workflows, and other parts of the app can exchange data and trigger behavior on systems you control.
Typical uses include syncing CRM or ticketing data, running custom business logic when an employee reaches a step in a flow, or bridging Atonom to internal APIs.
## How it works
1. **Create a connector in Atonom** — Register a connector in the dashboard so Atonom knows it exists and can route traffic to it.
2. **Configure actions** — For each action, point Atonom at the HTTP/GRPC endpoints on your server that should run when that action is invoked.
3. **Implement your endpoints** — Handle incoming requests using the contract documented in the API reference (authentication, payloads, and response shapes).
## Step 1: Create a connector in the app
In the Atonom application, navigate to your integrations page within your settings. Then click on the Integration Connectors tab, and choose **Create connector** and complete the required fields—such as a name and description—so the connector appears in your organization.
## Step 2: Point connector actions to your server
Each action represents something Atonom can invoke—for example when a Cloud Employee hits a step in a workflow or when another part of the product triggers that integration. In the connector settings, define each action and set the **base URL or endpoint** that should receive HTTP/GRPC requests from Atonom.
Requests are sent to **your** servers, so your team controls availability, scaling, and validation. Ensure endpoints use TLS and follow the request and response formats described in the reference.
## Step 3: Implement actions using the connector reference
To build compatible handlers, use the **Integration Connectors** tab in this documentation. It describes how Atonom calls your endpoints, including security expectations and payload schemas, so you can implement actions confidently.
Open the Integration Connectors reference for endpoint contracts and examples.
If anything in your connector setup is unclear, contact [support@atonom.ai](mailto:support@atonom.ai).
# Meeting Types
Source: https://docs.atonom.ai/integrations/meeting-types
Create and manage meeting types in Atonom, and understand how they work with calendar booking.
Meeting types are reusable booking templates that define how a schedulable meeting behaves—duration, slot spacing, lead times, reminders, and visibility. Every calendar booking in Atonom references a meeting type, whether the booking comes from a profile page, Cloud Employee, chat, form, or the API.
Before users can book meetings, your organization needs at least one meeting type configured, and each user who will receive bookings needs a connected calendar. See [Calendar Setup](/integrations/calendar-setup) for connecting Google or Microsoft and configuring personal meeting preferences.
## Meeting types vs personal calendar settings
Atonom separates **what kind of meeting** is being booked from **whose calendar** it lands on.
| | Meeting type | Personal calendar settings |
| ----------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Scope** | Organization (tenant) | Individual user |
| **Configured in** | Org Settings → Meetings | My Settings → My Calendar |
| **Examples** | Duration, slot interval, meeting-type lead time, max booking window | Personal meeting link, buffer time, personal lead time, weekly availability, selected calendars |
At booking time, Atonom combines both. For example, availability uses the **longer** of the meeting type's minimum lead time and the user's personal lead time, plus the user's buffer time and weekly hours. See [How lead time is applied](/integrations/calendar-setup#how-lead-time-is-applied) in the calendar setup guide.
```mermaid theme={null}
flowchart TD
MT[MeetingType tenant template] --> Book[Booking flow]
CS[User calendar settings] --> Book
Book --> Cal[Google or Microsoft calendar]
MT --> CE[Cloud Employee]
MT --> PP[Profile page]
MT --> API[Schedule Meeting API]
```
***
## Creating meeting types
1. Go to **Org Settings → Meetings** ([`/#/settings/v2/meeting_types`](https://app.getsignals.ai/#/settings/v2/meeting_types))
2. Click **Add Meeting**
3. Fill in the meeting type fields (see below)
4. Click **Save**
You can edit or delete existing meeting types from the same page. Deleted meeting types are soft-deleted and no longer appear in booking flows.
Org Settings → Meetings requires the Calendar plan component on your tenant.
### Meeting type fields
| Field | Description |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Meeting Name** | Label shown to visitors when choosing a meeting (for example, "Product Demo" or "30-Minute Consultation") |
| **Meeting Duration** | Length of the booked event: 15, 30, 45, or 60 minutes |
| **Time Slot Interval** | How often available start times appear (every 5, 10, 15, 30, or 60 minutes). Defaults to 15 minutes |
| **Reminder Time** | Calendar reminder for the host before the meeting: 15 min, 30 min, 1 hour, 2 hours, 12 hours, or 1 day before |
| **Minimum Lead Time** | Earliest a meeting can start after it is booked. Options from 15 minutes up to 2 days |
| **Maximum Lead Time** | How far in advance slots can be offered, in days (1–21; defaults to 14 days) |
| **Meeting Description** | Details included on calendar invitations |
| **Visibility** | **Available company-wide** — any user in the org can see and use this type. **Private to me** — only visible to the user who created it |
| **Allow use on agent profile pages** | When enabled, users can add this meeting type to their public profile page |
Minimum lead time on the meeting type is compared against each user's **personal lead time** in My Calendar. Atonom always applies whichever value is **longer**.
***
## Where meeting types are used
Once created, meeting types can power bookings across Atonom:
| Surface | How the meeting type is selected |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| **Profile pages** | User adds types to **Agent Page Meetings** on My Profile; visitors pick from those types |
| **Cloud Employees** | Meeting booking capability references a specific meeting type |
| **Comm Agents / workflows** | Calendar book-meeting tool configured with a meeting type |
| **Chat & forms** | Calendar drop or form field tied to a meeting type |
| **Schedule a Meeting API** | `meeting_type_id` in the API request |
Each surface validates that the meeting type exists, is visible to the booking user, and (for profile pages) is enabled for agent pages.
***
## Profile pages and meeting types
Profile page booking is optional and separate from other flows. See [Profile page meeting booking](/integrations/calendar-setup#profile-page-meeting-booking-optional) for the full setup.
When profile booking is enabled, users manage two lists under **My Settings → My Profile → My Meetings**:
### Agent Page Meetings
Meeting types currently shown on the user's public profile page. Anyone with the profile link can schedule one of these types.
* Use **Copy link** next to a meeting type to get a direct URL that opens the profile page with that type pre-selected (`?m_id=`)
* Use **Remove** to take a type off the profile page without deleting the meeting type itself
### Available Meetings
Meeting types the user is allowed to add to their profile. A type appears here when it is:
* **Available company-wide**, or **Private to me** and created by the current user, **and**
* Has **Allow use on agent profile pages** enabled in Org Settings
Click **+** to add a type from Available Meetings to Agent Page Meetings.
A meeting type must have **Allow use on agent profile pages** checked when it is created or edited in Org Settings → Meetings, or users will not be able to add it to their profile.
***
## Scheduling rules at book time
When a visitor or Cloud Employee books a meeting, Atonom applies rules from the meeting type and the host's personal calendar settings:
| Rule | Source |
| ------------------------ | ------------------------------------------------------------------------ |
| Event duration | Meeting type duration |
| Slot spacing | Meeting type time slot interval |
| Minimum notice | **Longer of** meeting type minimum lead time and user personal lead time |
| Booking window | Meeting type maximum lead time (days) |
| Gap after prior meetings | User buffer time (My Calendar → Meeting Settings) |
| Bookable hours | User weekly availability grid (My Calendar → Availability Settings) |
| Conflict checks | User selected calendars |
| Meeting link in invite | User personal meeting link (My Calendar → Meeting Settings) |
| Calendar reminder | Meeting type reminder time |
***
## Cloud Employee meeting booking
To let a Cloud Employee schedule meetings on behalf of users:
1. Create meeting types in **Org Settings → Meetings**
2. Ensure target users have connected calendars and configured availability — see [Calendar Setup](/integrations/calendar-setup)
3. On the Cloud Employee, enable the **Meeting booking** capability and select a meeting type
4. Configure routing so the employee knows which user's calendar to book against
The Cloud Employee uses the selected meeting type's duration, interval, and lead-time rules when offering and confirming slots. It does not require the host to enable profile page booking.
See [Build Your First Cloud Employee](/get-started/quickstart) for capability setup steps.
***
## Troubleshooting
| Issue | What to check |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| No meeting types in dropdowns | Create at least one type in Org Settings → Meetings |
| Type not in Available Meetings on profile | Confirm **Allow use on agent profile pages** is enabled; confirm visibility (company-wide or private to creator) |
| No meetings shown on profile page | User must enable profile booking, connect calendar, and add types under Agent Page Meetings |
| Slots start too soon or too late | Compare meeting type minimum lead time with user's personal lead time — the longer value wins |
| No slots far in the future | Check meeting type **Maximum Lead Time** (days) |
| Slots too close together or far apart | Adjust meeting type **Time Slot Interval** |
| Booking succeeds but no meeting link | User must save a personal meeting link in My Calendar → Meeting Settings |
Contact [support@atonom.ai](mailto:support@atonom.ai) if you need assistance.
***
## What's next
Connect Google or Microsoft, and configure personal meeting and availability settings
Google and Microsoft scopes and admin setup
Book meetings programmatically with a meeting type ID
Enable the meeting booking capability on a Cloud Employee
# Webhook Authorization
Source: https://docs.atonom.ai/webhooks/authorization
Verify that webhook HTTP requests were sent by Atonom using the JWT in the Authorization header.
Each webhook delivery includes a short-lived **signed JWT** in the standard HTTP `Authorization` header.
Your server can verify the signature with the **webhook public key** shown in Atonom so you know the request originated from us.
The delivery service sets the header like this:
```
Authorization: Bearer
```
## How verification works
1. **Read the bearer token** from `Authorization` (scheme `Bearer`, case-insensitive).
2. **Verify the JWT** using your webhook **RSA public key** in PEM form (`-----BEGIN PUBLIC KEY-----`). The token is signed with **PS256** (RSA-PSS with SHA-256).
3. **Validate claims** after verification succeeds:
* **`exp`**: token expiry (tokens are valid for a short window, currently five minutes from issuance).
* **`iat`**: issued-at time (optional sanity check vs your server clock).
* **`tenant_id`**: Atonom tenant that sent the event. You can compare this to the `tenant_id` field in the JSON body of the same request for consistency.
The JWT payload is not encrypted; only the **signature** proves authenticity.
## Get your webhook public key
1. Log in to your Atonom account at `https://app.getsignals.ai`
2. Navigate to `https://app.getsignals.ai/#/settings/security`
3. Open the accordion card titled **Webhook Verification**
4. Copy the **public key** (PEM text)
## Example: JavaScript (Node.js)
Use a library that supports **PS256**, for example [`jose`](https://github.com/panva/jose):
```bash theme={null}
npm install jose
```
```javascript theme={null}
import * as jose from "jose";
const WEBHOOK_PUBLIC_KEY_PEM = process.env.ATONOM_WEBHOOK_PUBLIC_KEY; // full PEM string
/**
* @param {import('http').IncomingMessage | { headers: Record }} req
* @returns {Promise}
*/
export async function verifyAtonomWebhook(req) {
const raw = req.headers["authorization"] ?? req.headers["Authorization"];
const auth = Array.isArray(raw) ? raw[0] : raw;
if (!auth || typeof auth !== "string") {
throw new Error("Missing Authorization header");
}
const m = auth.match(/^Bearer\s+(.+)$/i);
if (!m) {
throw new Error("Authorization must be a Bearer token");
}
const token = m[1].trim();
const publicKey = await jose.importSPKI(WEBHOOK_PUBLIC_KEY_PEM, "PS256");
const { payload } = await jose.jwtVerify(token, publicKey, {
algorithms: ["PS256"],
clockTolerance: 60, // seconds; optional, helps with clock skew
});
return payload;
}
```
## Example: Python
Use **PyJWT** with the **cryptography** backend so **PS256** is available:
```bash theme={null}
pip install PyJWT cryptography
```
```python theme={null}
import os
import re
import jwt
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.backends import default_backend
WEBHOOK_PUBLIC_KEY_PEM = os.environ["ATONOM_WEBHOOK_PUBLIC_KEY"] # full PEM string
_bearer_re = re.compile(r"^Bearer\s+(.+)$", re.IGNORECASE)
def verify_atonom_webhook(authorization_header: str | None) -> dict:
if not authorization_header:
raise ValueError("Missing Authorization header")
m = _bearer_re.match(authorization_header.strip())
if not m:
raise ValueError("Authorization must be a Bearer token")
token = m.group(1).strip()
public_key = serialization.load_pem_public_key(
WEBHOOK_PUBLIC_KEY_PEM.encode("utf-8"),
backend=default_backend(),
)
payload = jwt.decode(
token,
public_key,
algorithms=["PS256"],
options={"require": ["exp", "iat", "tenant_id"]},
leeway=60, # seconds; optional clock skew tolerance
)
return payload
```
If verification fails, respond with **401 Unauthorized** (or reject the connection in your framework’s idiomatic way) and do not treat the payload as trusted.
# Inbound Voice Call
Source: https://docs.atonom.ai/webhooks/inbound-voice-call
Learn how to handle inbound voice call event data from Atonom
Atonom offers several kinds of voice chat event types that can be sent to your webhook URLs.
> To learn how to specify webhook URLs for your cloud employees in the Atonom app, please see the [webhook URLs](/get-started/quickstart/#configure-webhook) configuration step in the quickstart guide.
Below you will find an example of the data structure for inbound voice calls.
## Inbound Call Webhook
**Event Types:**
* call\_inbound: Triggered when an inbound call is received
When an inbound call is received, Atonom will send a webhook request to your configured endpoint. You can respond with additional information to customize how the Cloud Employee handles the call.
#### Webhook Request from Atonom
```json theme={null}
{
"event": "call_inbound",
"call_inbound": {
"agent_id": "7",
"from_number": "+11234567890",
"to_number": "+10987654321",
"tenant_id": 123
}
}
```
#### Response Format
You can respond with the following structure to customize the call handling:
```json theme={null}
{
"call_inbound": {
"override_agent_id": "5", // Optional: Override the default agent
"dynamic_variables": {
"email": "example@email.com",
"first_name": "John",
"last_name": "Doe"
},
"meta_data": {
"company": "Example Company",
"first_name": "John",
"last_name": "Doe",
"title": "Analyst"
}
}
}
```
#### Response Fields
| Field | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `override_agent_id` | Optional. Specify a different agent ID to handle the call |
| `dynamic_variables` | Variables that can be used in the Welcome Message or prompting using syntax. |
| `meta_data` | Information that the Cloud Employee will know throughout the entire conversation. The agent can reference this information when answering questions. |
#### Usage Notes
1. **Dynamic Variables**
* Can be used in the Welcome Message and prompting using syntax
* Example: "Hello , welcome to our company!"
* The Cloud Employee does not access these variables during the conversation they are only used for dynamic variables in prompts and welcome messages
2. **Meta Data**
* Available throughout the entire conversation
* The Cloud Employee can reference this information when answering questions
* Example: If you ask "What's my name?", the agent can answer using the `first_name` from meta\_data
3. **Response Time**
* Your webhook endpoint should respond within 5 seconds
* If no response is received, the call will proceed with default settings
#### Example Scenarios
1. **Basic Response with Dynamic Variables**
```json theme={null}
{
"call_inbound": {
"dynamic_variables": {
"first_name": "John",
"company": "Acme Corp"
}
}
}
```
Welcome Message: "Hello `first_name`, welcome to `company`!"
2. **Full Response with Meta Data**
```json theme={null}
{
"call_inbound": {
"dynamic_variables": {
"first_name": "John"
},
"meta_data": {
"company": "Acme Corp",
"title": "Senior Developer",
"department": "Engineering"
}
}
}
```
The Cloud Employee can now:
* Greet the caller using their first name
* Answer questions about their company, title, and department throughout the call
# Outbound Voice Call
Source: https://docs.atonom.ai/webhooks/outbound-voice-call
Learn how to handle outbound voice call event data from Atonom
Atonom offers several kinds of voice chat event types that can be sent to your webhook URLs.
> To learn how to specify webhook URLs for your cloud employees in the Atonom app, please see the [webhook URLs](/get-started/quickstart/#configure-webhook) configuration step in the quickstart guide.
We currently only send a call\_analyzed event at the moment to not spam your webhook.
Below you will find an example of the data structure for outbound voice calls.
## Webhook Response Structure
When an outbound call event occurs, Atonom will send a webhook response with the following structure:
```json theme={null}
{
"event": "call_analyzed",
"call": {
"call_type": "phone",
"call_direction": "outbound",
"from_number": "+1234567890",
"to_number": "+1234567890",
"call_duration": 120,
"call_start_time": "1972-01-01T00:00:00Z",
"call_end_time": "1972-01-01T00:00:00Z",
"call_status": "completed",
"metadata": {},
"extracted_variables": {
"name": "Susan",
"email": "susan@example.com",
"phone": "+1234567890",
"company": "Example Inc.",
"title": "VP of Sales"
},
"disconnect_reason": "user_hangup",
"transcript": "Agent: Hello I'm Emma, what can I help you with today?\n...",
"transcript_object": [
{
"role": "agent",
"content": "Hello I'm Emma, what can I help you with today?",
"metadata": {
"response_id": 0,
"knowledge_base_content": [
"{Title: Salutation}\n\nBe friendly when introducing yourself.",
...
]
}
},
{
"role": "user",
"content": "Hi Emma, I want to learn more about your company!"
},
...
],
"transcript_with_tool_calls": [ [Object], [Object], ... ],
"meeting_event": {
"id": 123,
"name": "...",
"agent_name": "...",
"date": "1972-01-01",
"duration_minutes": 120,
"lead_time_minutes": 10
},
"opt_out_sensitive_data": false,
"call_analysis": {
"call_summary": "...",
"in_voicemail": false,
"user_sentiment": "...",
"call_successful": true,
"custom_analysis_data": {
"failed_qualified_question": ""
}
}
}
}
```
If metadata or custom variables are empty they will be omitted from the webhook event payload
#### Key Fields
| Field | Description |
| -------------------------- | ----------------------------------------------------------------------- |
| `event` | The type of call event (`call-start`, `call-ended`, or `call-analyzed`) |
| `call.call_type` | Type of call (always "phone" for voice calls) |
| `call.call_direction` | Direction of the call (always "outbound") |
| `call.from_number` | The phone number that initiated the call |
| `call.to_number` | The phone number that received the call |
| `call.call_duration` | Duration of the call in seconds |
| `call.call_status` | Status of the call (e.g., "completed", "failed", "busy") |
| `call.extracted_variables` | Information extracted during the call |
| `call.transcript` | The full conversation transcript |
| `call.call_analysis` | Analysis results including summary and sentiment |
#### Usage Notes
1. **Call Status**
* `completed`: Call ended normally
* `failed`: Call failed to connect
* `busy`: Recipient was busy
* `no_answer`: Call was not answered
* `voicemail`: Call went to voicemail
2. **Call Analysis**
* Available only in `call-analyzed` events
* Includes sentiment analysis and call summary
* May contain custom analysis data based on your configuration
3. **Transcripts**
* `transcript`: Plain text version of the conversation
* `transcript_object`: Structured version with speaker information and knowledge base context
* `transcript_with_tool_calls`: Includes tool usage during the call
# Web Chat
Source: https://docs.atonom.ai/webhooks/web-chat
Learn how to use the web chat webhook to integrate your Cloud Employee with your existing systems
Atonom offers several kinds of web chat event types that can be sent to your webhook URLs.
> To learn how to specify webhook URLs for your cloud employees in the Atonom app, please see the [webhook URLs](/get-started/quickstart/#configure-webhook) configuration step in the quickstart guide.
Below you will find an example of the data structure for web chat events.
## Web Chat Structure
**Event Types:**
* conversation-start: Triggered when a new web chat conversation begins
* conversation-closed: Triggered when a web chat conversation ends
### Webhook Response Structure
When a web chat event occurs, Atonom will send a webhook response with the following structure:
```json theme={null}
{
"event": "conversation-closed",
"chat": {
"transcript": "...",
"meeting_event": {
"id": 123,
"name": "...",
"agent_name": "...",
"date": "1972-01-01",
"duration_minutes": 120,
"lead_time_minutes": 10
},
"user_emails": {
"last_routed": "example1@example.com",
"last_routed_user_id": 1,
"closed_conversation": "example2@example.com",
"closed_conversation_user_id": 2,
"meeting_scheduled": "example3@example.com",
"meeting_scheduled_user_id": 3
},
"referrer": "Direct",
"source_type": "Direct Traffic",
"traffic_source": "Source",
"traffic_campaign": "Campaign"
},
"contact": {
"tenant_id": 1,
"first_name": "John",
"last_name": "Smith",
"middle_name": "Robert",
"preferred_name": "Johnny",
"name": "John Smith",
"honorific": "Mr.",
"phone": "+1 (555) 123-4567",
"home_phone": "+1 (555) 987-6543",
"mobile_phone": "+1 (555) 234-5678",
"other_phone": "+1 (555) 876-5432",
"email": "john.smith@example.com",
"other_email": "johnny.smith@gmail.com",
"birthdate": "1985-06-15T00:00:00Z",
"description": "Senior Software Engineer with 10+ years of experience",
"title": "Senior Software Engineer",
"lead_source": "Website Form",
"lead_score": 85,
"created_by_user_id": 123,
"company_name": "TechCorp Inc.",
"company_website": "https://techcorp.example.com",
"company_industry": "Technology",
"company_employee_count": "500-1000",
"company_revenue": "$10M-$50M",
"enriched_fields": ["company_name", "title", "linkedin_handle"],
"enriched_timestamp": "2024-03-20T15:30:00Z",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"bio": "Experienced software engineer specializing in cloud architecture and microservices",
"role": "Senior Software Engineer",
"seniority": "Senior",
"linkedin_handle": "johnsmith",
"company_sector": "Enterprise Software",
"company_phone": "+1 (555) 555-5555",
"company_description": "Leading provider of cloud-based enterprise solutions",
"company_location": "San Francisco, CA",
"company_timezone": "America/Los_Angeles",
"company_twitter_handle": "techcorp",
"company_tech": ["Python", "AWS", "Docker", "Kubernetes", "React"],
"company_linkedin_handle": "techcorp-inc",
"avatar_url": "https://example.com/avatars/john-smith.jpg",
"company_avatar_url": "https://example.com/company-logos/techcorp.png",
"facebook_handle": "john.smith.123",
"twitter_handle": "johnsmith",
"instagram_handle": "johnsmith",
"domain": "example.com",
"source": "form",
"source_id": 456,
"traffic_source": "Google",
"persona_id": 789,
"custom_fields": {
"department": "Engineering",
"project_interest": "Cloud Migration",
"budget_range": "$50,000-$100,000",
"timeline": "Q2 2024"
}
}
}
```
Contact will be omitted from the data if the conversation was not with a new/current contact in Atonom.
#### Key Fields
| Field | Description |
| -------------------- | -------------------------------------------------------------------------- |
| `event` | The type of web chat event (`conversation-start` or `conversation-closed`) |
| `chat.transcript` | The full conversation transcript |
| `chat.meeting_event` | Details about any scheduled meeting during the chat |
| `chat.user_emails` | Information about users involved in the conversation |
| `contact` | Contact information if the chat was with a known contact |