Heedify AI Receptionist (AIR): AI Voice Agent
Heedify AI Receptionist (AIR) is an AI receptionist for Microsoft Teams, built as an AI voice agent. Heedify supports AI call answering via an agent that holds a natural-language conversation with the caller, integrated with Microsoft Teams Phone Extensibility and Azure Communication Services. It answers on its own Teams resource account, understands what the caller wants, answers from your knowledge base, and transfers the call to a queue, a Teams user, a Teams call queue or an external number, with the conversation context. Heedify AIR is certified for Microsoft Teams.
Certified for Microsoft Teams: Heedify AIR is certified under the Microsoft Teams Voice Agent Program. It runs on Teams Phone Extensibility (the Unify model) with Azure Communication Services.
The AI Agent module is enabled per tenant by Heedify and requires permissions on call flows. If it is not in your sidebar, contact sales@heedify.io. Heedify AIR uses the Unify model: see Unify Model Requirements.
Consent for the AI Voice Agent
Before the first agent, a Microsoft 365 administrator grants consent to the Heedify AI Voice Agent application, once per tenant:
- Open Global Settings from the sidebar.
- Open the Heedify AI Voice Agent tab. It is shown only when the AI Agent module is enabled for your tenant.
- Click Consent Permissions next to Heedify AI Voice Agent, sign in as a Microsoft 365 administrator and accept.
See Grant consents for how consent works in Heedify.
How a call flows through Heedify AIR
- The caller dials the number of the agent’s Teams resource account.
- The agent says its Greeting Sentence, detects the caller’s language and replies in it.
- It works out the caller’s intent from the conversation, the keywords of your Routes, or both (the Strategy), and asks a clarifying question if the intent is unclear.
- It answers from the Knowledge Base, looks up a colleague in the Teams directory, checks their presence, or takes a message.
- It transfers the call to the destination of the matching route, after the route’s Announcement. If the intent stays unclear, it uses the Fallback destination.
Creating an AI agent
- Grant the consent for the AI Voice Agent (see above), if not already done.
- Create a Teams resource account for the agent, linked to Heedify Unify, and assign it a phone number. The PowerShell steps are the same as for a Unify call flow: see Create the Teams resource account (Unify model).
- Open AI Agent from the sidebar, then click New AI Agent.
- On the Identity tab, search for the resource account, select the Entity and enter the Agent Name.
- Set the voice, personality and greeting on the Voice & Languages, Personality and Greeting & Behavior tabs.
- On the Routing tab, add the routes the agent can transfer to, and the fallback destination.
- Optionally fill in Knowledge Base, Skills and Security & Errors.
- Click Save, then call the number to test the agent.
Agent Name and Entity are required. The resource account becomes the agent’s identifier and cannot be changed after creation.
Identity
| Field | Description |
|---|---|
| Resource account | Teams resource account the agent answers on, found by search. Creation only. |
| Resource Account ID | Identifier of the selected resource account (read-only). |
| Resource Account Name | Name of the resource account (read-only, shown when editing). |
| Entity | Entity that owns the agent. Required, set at creation. |
| Agent Name | Name the agent introduces itself with. Required. |
| Role | Role the agent states (e.g. receptionist). |
| Company | Company name the agent states. |
Voice & Languages
| Field | Description |
|---|---|
| Voice | Voice of the agent: marin (default), cedar, alloy, ash, ballad, coral, echo, sage, shimmer or verse. |
| Automatic language detection enabled | The agent detects the caller’s language and replies in it. No language list is needed. |
| Language detection protocol (rules) | Ordered steps the agent follows to detect and lock onto the caller’s language. |
Personality
| Field | Description |
|---|---|
| Personality Tone | Friendly & Casual (default), Friendly & Professional or Formal. |
| Language Style | Free text describing the style of speech (default formal-polite). |
Greeting & Behavior
| Field | Description |
|---|---|
| Greeting Sentence | First sentence of the call. Placeholders: {name}, {role}, {company}. A Preview shows the result. Required. |
| General Behavior Rules | Free rules the agent always follows (e.g. Never interrupt the user). |
| Greeting is mandatory at call start | The agent always greets first. On by default. |
| Must include all elements (name, role, company) | The greeting must contain all three. On by default. |
| Maximum sentences per reply | Keeps answers short. Default 2. |
| Avoid repeating what was already said | Avoids repetitions. |
| Confirm verbally before any action (transfer, hangup…) | The agent asks the caller to confirm before acting. |
Skills
Each skill can be turned on or off. Click a skill to open its settings.
| Skill | What it does | Settings |
|---|---|---|
| Directory Lookup | Searches for a user in the Microsoft Teams directory. | None |
| Presence Check | Checks a user’s real-time Teams availability. | Announce the status to the caller |
| Transfer to User | Transfers the call to a Teams user. | Require verbal confirmation before action |
| Transfer to Phone | Transfers the call to an external phone number. | Require verbal confirmation before action |
| Hangup | Ends the call after the farewell. Always on. | Farewell message |
| Leave a Message | Takes a message for an unavailable user and sends it via Teams. | Information to capture: caller name, phone number, message content |
Custom CRM / API connectors
Click Add a custom connector to let the agent read data from your CRM or API when the call starts, for example to greet a known customer by name. At runtime, the first enabled read connector provides this context.
| Field | Description |
|---|---|
| Name | Name of the connector. |
| Mode | Read at answer (fetch context when the call starts) or Update (send a request during or after the call). |
| Request URL | HTTPS endpoint. Plain HTTP is refused. |
| Method | HTTP method of the request. |
| Headers | Request headers (e.g. an API key). |
| Send a custom JSON body / Request body (free JSON) | Optional body of the request. |
| Response mapping | variable ← JSON path (dot notation, array index allowed, e.g. Cases.0.Status). Each variable becomes usable as $variable$. |
| Allowed hosts | Optional list of hosts the request may reach. When set, the URL’s host must be in it. |
| Timeout (s) | Maximum wait for the response. Default 10. |
| Usage instructions | Tells the agent how to use the mapped $variables$ (e.g. Greet the caller by $clientName$ in your first reply). |
| Context injection template | How the fetched data is written into the agent’s context. If empty, every mapped field is listed. |
Example: greet a known customer
The request can use $callerPhoneNumber$ (the caller’s number, also available as $callerId$), $tenantId$ and $flowId$. With Request URL https://crm.example.com/api/contacts?phone=$callerPhoneNumber$ and Method GET, your CRM answers:
{
"contact": { "id": "C-10482", "firstName": "Claire", "lastName": "Martin", "segment": "Pro" },
"Cases": [
{ "Id": "CS-2291", "Status": "Open", "Subject": "Invoice dispute" },
{ "Id": "CS-1980", "Status": "Closed", "Subject": "Delivery delay" }
]
}
Response mapping turns this answer into variables:
| Variable | JSON path | Value for this call |
|---|---|---|
clientName |
contact.firstName |
Claire |
clientSegment |
contact.segment |
Pro |
lastCaseStatus |
Cases.0.Status |
Open |
lastCaseSubject |
Cases.0.Subject |
Invoice dispute |
Cases.0 is the first item of the Cases list: Cases.1.Status would give Closed.
The variables are then used in two places:
- Usage instructions:
Greet the caller by $clientName$ in your first reply.andIf $lastCaseStatus$ is Open, ask whether the call is about $lastCaseSubject$. - Context injection template:
Customer: $clientName$ ($clientSegment$). Last case: $lastCaseSubject$, status $lastCaseStatus$.
When Claire calls, the agent already knows who she is and opens with: “Hello Claire, are you calling about your invoice dispute?”. If the CRM does not answer in time or returns an error, the agent continues the call normally, without this context.
Routing
The routing tab defines where the agent can transfer a call.
| Field | Description |
|---|---|
| Strategy | How the intent is found: Conversational (from the dialogue, default), Keyword (keywords only) or Hybrid (keywords and conversation). |
| Ask a clarifying question before routing when intent is unclear | On by default. |
| Maximum clarifying questions | Default 1. |
| Routes | One entry per destination. Click Add route. |
| Fallback destination (when intent stays unclear) | Where the call goes when no route matches. |
| Disambiguation message | What the agent says when it cannot decide (EN and FR). |
| Qualification rules | Ordered rules the agent applies to decide how and where to route the caller. |
Each route has these fields:
| Field | Description |
|---|---|
| Route to | Destination type and target: Queue (a Heedify queue), Teams user, Phone number or Teams Call Queue (a Teams resource account). |
| Intent | Short internal key for the route (e.g. support). |
| Description (when to use this route) | Plain description the agent uses to recognise the request. |
| Keywords | Keywords in English (EN) and French (FR). |
| Example phrases | Typical caller sentences (e.g. I have a problem with my invoice). |
| Announcement (spoken before transfer) | Sentence said before transferring, in English and French. |
Knowledge Base
| Field | Description |
|---|---|
| Knowledge base enabled | Turns the knowledge base on. Off by default. |
| Name | Name of the knowledge base. |
| Primary language | en or fr. |
| Source format | Q&A (JSON), Markdown / Text (inline) or External URL. |
| Usage instructions | How the agent should use the knowledge base. |
| Fallback message | What the agent says when the answer is not in the knowledge base. |
| Q&A data (JSON) | Q&A format: a list of { "question": "…", "answer": "…" }. |
| Markdown / Text content | Inline format: injected as-is, up to about 3 pages (8,000 characters). Longer text is truncated. |
| URL / URL content format / Fetch timeout (s) | External URL format: link to a .md or .txt file, a JSON Q&A file or a web page, its format (text / markdown, json, html) and the fetch timeout (default 10 s). |
Security & Errors
| Field | Description |
|---|---|
| Security rules | Rules the agent must never break (e.g. never give personal data of a colleague). |
| Max retries | Number of attempts before an error message. Default 3. |
| Fallback to human | On error, the call goes to a human. On by default. |
| Fallback queue (when intent stays unclear) | Queue used for the fallback to a human. |
| User not found / Transfer failed / Technical error / Timeout | Message the agent says for each error. |
Advanced
| Field | Description |
|---|---|
| Agent enabled | Turns the agent on or off. |
| Region | Europe (EU), United States (US) or Asia-Pacific (APAC). Default EU. |
| Data location | Where call data is stored. Default Europe. |
| Timezone | IANA name, e.g. Europe/Amsterdam. |
| Analytics | Track conversations, Track tools usage, Track language detection, Track qualification route, Track sentiment, and the Log level (debug, info, warn, error). |
| Advanced delays | Delay before transfer, Delay before hangup, Audio commit delay, Barge-in audio delay (ms). Leave the defaults unless you know what you are doing. |
| Voice activity detection | Interruption threshold (0.3 – 0.9): higher means background noise interrupts the agent less, but a soft-spoken caller may be missed (default 0.5). Silence before end of turn (ms): default 500. |
Editing and deleting
Open an agent from the AI Agents list to edit it. The resource account and the Entity cannot be changed after creation. Deleting an agent removes it from Heedify; the Teams resource account and its number stay in Microsoft Teams.
Works with: Microsoft Teams, Teams Phone Extensibility, Azure Communication Services, Microsoft 365 presence, Queues, HTTPS CRM and API connectors.
FAQ
What is Heedify AIR? Heedify AIR is an AI voice agent for Microsoft Teams. It answers calls on a Teams resource account, understands what the caller wants in natural language, answers from your knowledge base, and transfers the call to a queue, a Teams user, a Teams call queue or an external number.
Which languages does Heedify AIR speak? The agent detects the caller’s language from the first words and replies in it. No language list needs to be configured; the knowledge base has a primary language (English or French).
Is Heedify AIR certified by Microsoft? Yes. Heedify AIR is certified for Microsoft Teams under the Microsoft Teams Voice Agent Program. It runs on Teams Phone Extensibility (the Unify model) with Azure Communication Services.
Which consent does Heedify AIR need? A Microsoft 365 administrator grants consent to the Heedify AI Voice Agent application once per tenant, in Global Settings, on the Heedify AI Voice Agent tab, with Consent Permissions.
Why don’t I see AI Agent in the Admin Portal sidebar? The AI Agent module is enabled per tenant by Heedify, and it requires permissions on call flows. Contact sales@heedify.io to enable it.