Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Microsoft Teams

Agenten mit Chats und Erwähnungen in Microsoft Teams starten, über deinen eigenen Azure Bot, und ihre Antworten in der Unterhaltung oder einem Kanal posten.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typteams
ZugangsdatenEin Kontozugang (Connection) vom Typ teams mit Microsoft-App-ID, Tenant-ID und Clientgeheimnis deines eigenen Azure Bots für einen einzelnen Tenant
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede Nachricht startet alle verknüpften Agenten.
Während der PauseNachrichten starten keine Runs. Outbound sendet nichts.

Einrichtung

  1. Lege einen Azure Bot für einen einzelnen Tenant an und aktiviere für ihn Microsoft Teams. Kopiere seine Microsoft-App-ID, seine App-Tenant-ID und den Wert eines Clientgeheimnisses.

  2. Klicke unter Project Settings → Connections auf New connection und wähle Microsoft Teams. Den Kontozugang kannst du auch im Formular der Verbindung über die Auswahl unter Connection anlegen.

  3. Gib unter Bot einen Connection name ein, den Bot name, den die Leute in Teams sehen, sowie Microsoft App ID, Tenant ID und Client secret. Sollen die Agenten jede Nachricht in den Kanälen eines Teams erhalten und nicht nur Erwähnungen, schalte Receive all channel messages ein. Klicke auf Create connection. Bevor connic die Werte speichert, meldet es sich damit als Bot an und prüft sie so.

  4. Kopiere unter Messaging endpoint die URL, die connic anzeigt. Füge sie im Azure-Portal auf der Seite Configuration des Bots als Messaging endpoint ein und übernimm die Änderung. Klicke auf Continue.

  5. Klicke unter Teams app auf Download app package und lade das Paket in Teams hoch; siehe Teams-App. Füge die App den Teams, Gruppenchats und Personen hinzu, die sie nutzen sollen, und klicke auf Done.

  6. Öffne den Agenten. Klicke im Connector Flow für Nachrichten auf Add inbound connector oder für Antworten und Beiträge auf Add outbound connector. Klicke dann auf Create New Connector und wähle Microsoft Teams.

  7. Wähle den Modus, Inbound (Messages) oder Outbound (Send Messages), und unter Connection den Kontozugang. Für Outbound kannst du einen Default channel einfügen. Klicke auf Create. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.

Im Code

Deklariere die Verbindung in connectors/*.yaml. connection nennt den Kontozugang mit dem Bot. Inbound-Verbindungen brauchen kein config, Outbound-Verbindungen nehmen optional einen channel.

connectors/teams-helpdesk.yaml
type: teams
mode: inbound
connection: support-bot   # Kontozugang mit dem Azure Bot
agents:
  - helpdesk
connectors/teams-replies.yaml
type: teams
mode: outbound
connection: support-bot
config:
  channel: https://teams.microsoft.com/l/channel/19%3A7c41e2a9b3d8%40thread.tacv2/Allgemein
agents:
  - name: helpdesk
    outbound: { usage: automatic }

Konfiguration

Die Felder einer Microsoft-Teams-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Der Microsoft-Teams-Kontozugang, den sie nennen, muss im Dashboard fertig eingerichtet sein; bis dahin schlagen Deployment oder Anfrage fehl. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.

FeldTypStatusBeschreibung
typestringErforderlichteams.
modestringErforderlichinbound oder outbound. Dashboard: Mode.
connectionstringErforderlichInbound und Outbound. Name oder ID eines fertig eingerichteten Microsoft-Teams-Kontozugangs. Siehe Azure Bot. Dashboard: Connection.
configobjectOptionalEinstellungen der Teams-Verbindung. Inbound-Verbindungen haben keine.
channelstringOptionalOutbound. Der Kanal für Runs, die nicht in Teams begonnen haben: ein Link aus Get link to channel in Teams oder eine Kanal-ID wie 19:7c41e2a9b3d8@thread.tacv2. Dashboard: Default channel.

Name und Zugangsdaten des Bots sowie Receive all channel messages gehören zum Kontozugang, nicht zur Verbindung.

Erzeugte Werte

connic erzeugt diese Werte am Kontozugang, alle Verbindungen mit diesem Kontozugang teilen sie also.

WertModiBeschreibung
Messaging endpointInbound, OutboundHierhin sendet Teams die Nachrichten an den Bot, eine URL pro Kontozugang: https://connect.connic.co/teams/<connection id>. Du trägst sie auf der Seite Configuration des Bots im Azure-Portal ein.
Teams-App-PaketInbound, OutboundEine ZIP-Datei mit manifest.json und den Icons der App, zum Hochladen in Teams. Download app package im Detailbereich des Kontozugangs lädt sie herunter.
Installierte TeamsInbound, OutboundDie Teams, denen die App hinzugefügt wurde, so wie Teams die Installationen meldet. Der Detailbereich des Kontozugangs listet sie auf.

Agent-Input

Modi: Inbound

Eine Inbound-Verbindung startet einen Run für jeden verknüpften Agenten, sobald jemand dem Bot im Chat schreibt oder ihn in einem Kanal oder Gruppenchat erwähnt. Ist Receive all channel messages an, startet jede Nachricht in den Kanälen der Teams, denen die App hinzugefügt wurde, Runs, nicht nur Erwähnungen. connic bestätigt Teams jede Nachricht sofort und startet die Agenten danach. Der Run erhält:

payload.json
{
  "text": "Kann ich nicht genommene Urlaubstage ins nächste Jahr mitnehmen?",
  "conversation_id": "teams:19:4f2a9c1e7b3d@thread.tacv2;messageid=1794873600000",
  "conversation_type": "channel",
  "mentioned": true,
  "sender": {
    "id": "29:1kXz7Qv3mJt0aB8yRwE2",
    "aad_object_id": "5b0e8c4d-2f6a-4e1b-9c3d-7a8f1e2d4b6c",
    "name": "Jana Weber"
  },
  "team": { "id": "19:8d3e5f7a9b1c@thread.tacv2", "name": "HR" },
  "channel": { "id": "19:4f2a9c1e7b3d@thread.tacv2", "name": "Fragen an HR" },
  "message_id": "1794873600000",
  "raw": { ... }
}
  • text ist der Text der Nachricht ohne die Erwähnung des Bots.
  • conversation_id besteht aus teams: und der ID der Unterhaltung in Teams. Diese ID bleibt für alle Nachrichten eines Chats und eines Threads in einem Kanal gleich. Soll dein Agent die früheren Nachrichten als Verlauf kennen, setze in seiner YAML session.key: input.conversation_id. Von sich aus schaltet die Verbindung keine Sessions ein.
  • conversation_type ist personal für einen Chat mit dem Bot, groupChat oder channel. mentioned ist true, wenn die Nachricht den Bot erwähnt.
  • sender ist die Person, die geschrieben hat: ihre Benutzer-ID in Teams, ihre Objekt-ID in Microsoft Entra ID und ihr Anzeigename.
  • team und channel sind Team und Kanal einer Nachricht aus einem Kanal, in Chats sind beide null.
  • message_id ist die ID der Nachricht in Teams und raw die vollständige Aktivität, so wie Teams sie gesendet hat, samt den Angaben zu Anhängen.

Jede Inbound-Verbindung eines Kontozugangs erhält jede Nachricht an den Bot. Sollen mehrere Agenten starten, verknüpfe sie mit einer Inbound-Verbindung. Für getrennte Environments bekommt jedes Environment einen eigenen Bot mit eigenem Kontozugang. Nachrichten von außerhalb des Tenants des Bots ignoriert connic, und eine Nachricht, die Teams doppelt zustellt, startet keinen weiteren Run. Dateien und Bilder lädt connic nicht herunter und gibt sie nicht als Dateien an den Agenten weiter. Der Inbound-Modus antwortet nicht von selbst: Für eine Antwort in der Unterhaltung verknüpfst du den Agenten mit einer Outbound-Teams-Verbindung, die denselben Kontozugang nutzt; siehe Outbound-Zustellung.

Azure Bot

connic spricht mit Teams als dein eigener Azure Bot. Neue Bots für mehrere Tenants lässt Microsoft nicht mehr zu. Der Bot gilt deshalb für einen einzelnen Tenant und bedient nur deinen Microsoft-Entra-ID-Tenant. Seine Zugangsdaten liegen im Kontozugang, nicht in der Verbindung, und connic speichert sie verschlüsselt. Ein Kontozugang bedient beliebig viele Inbound- und Outbound-Verbindungen.

  1. Lege im Azure-Portal einen Azure Bot an. Wähle als Typ der App Single Tenant und lass eine neue Microsoft-App-ID erstellen.

  2. Kopiere auf der Seite Configuration des Bots die Microsoft App ID und die App Tenant ID.

  3. Klicke auf derselben Seite auf Manage Password. Erstelle unter Certificates & secrets der App-Registrierung ein Clientgeheimnis und kopiere seinen Wert.

  4. Füge unter Channels den Channel Microsoft Teams hinzu. Ohne ihn erreicht Teams den Bot nicht.

EinstellungBeschreibung
Bot nameDer Name, unter dem die Leute den Bot in Teams sehen, höchstens 30 Zeichen.
Microsoft App IDVon der Seite Configuration des Bots.
Tenant IDDie App Tenant ID von der Seite Configuration des Bots.
Client secretDer Wert eines Clientgeheimnisses unter Certificates & secrets der App-Registrierung des Bots, nicht seine Geheimnis-ID.
Receive all channel messagesOptional, standardmäßig aus. Jede Nachricht in den Kanälen der Teams, denen die App hinzugefügt wurde, erreicht die Inbound-Verbindungen, nicht nur Erwähnungen. Siehe Teams-App.

Bevor connic den Kontozugang speichert, meldet es sich als Bot an und prüft so Microsoft-App-ID, Tenant-ID und Clientgeheimnis. Das Clientgeheimnis läuft ab: Erstelle rechtzeitig ein neues und trage es im Kontozugang ein. Den Kontozugang richtest du im Dashboard ein. Verbindungen im Code, die REST API und connic MCP verweisen mit Name oder ID darauf.

Teams-App

In Teams erreichen die Leute den Bot über eine Teams-App mit dem Namen des Bots. connic baut das App-Paket aus dem Kontozugang: eine ZIP-Datei mit manifest.json und den Icons der App. Du lädst es mit Download app package im Detailbereich des Kontozugangs herunter. Hochladen kannst du es an zwei Stellen:

  • Im Teams Admin Center unter Teams apps → Manage apps → Upload new app.
  • In Teams als benutzerdefinierte App unter Apps → Manage your apps → Upload an app → Upload a custom app. Dafür muss das Hochladen benutzerdefinierter Apps im Tenant erlaubt sein.

Füge die App danach den Teams, Gruppenchats und Personen hinzu, die sie nutzen sollen. Teams meldet connic, wenn die App einem Team hinzugefügt wird, und der Detailbereich des Kontozugangs listet diese Teams auf. Aus denselben Meldungen erfährt connic, wohin es posten kann. Ein Standardkanal funktioniert deshalb erst, wenn die App im Team dieses Kanals installiert ist.

Mit Receive all channel messages fordert die App die ressourcenspezifische Berechtigung an, alle Nachrichten in den Kanälen eines Teams zu lesen. Ein Besitzer des Teams stimmt zu, wenn er die App dem Team hinzufügt. Danach erreicht jede Nachricht in den Kanälen dieses Teams die Inbound-Verbindungen, nicht nur Erwähnungen. In Gruppenchats kommen weiterhin nur Erwähnungen an.

Änderst du Bot name, Microsoft App ID oder Receive all channel messages, entsteht eine neue Version des App-Pakets. Lade sie erneut herunter und lade sie als Update derselben App hoch.

Outbound-Zustellung

Modi: Outbound

Eine Outbound-Teams-Verbindung postet bei jeder Nutzung eine Nachricht: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Dabei gilt die erste zutreffende Regel:

  1. Kam der Run über eine Inbound-Teams-Verbindung mit demselben Kontozugang, antwortet sie in dieser Unterhaltung: im Chat oder in einem Kanal im selben Thread.
  2. Sonst postet sie eine neue Nachricht im Default channel der Verbindung. Dafür muss die App im Team dieses Kanals installiert sein.

Trifft keine der beiden Regeln zu, schlägt die Zustellung mit einer Fehlermeldung fehl, die den Grund nennt.

Automatische Ausgabe

Eine automatische Verknüpfung postet die finale Ausgabe des Runs. Klartext wird zur Nachricht. Bei einem JSON-Objekt kommt die Nachricht aus text, body, message, response oder output, in dieser Reihenfolge. Teams stellt Markdown in der Nachricht formatiert dar.

output.json
{
  "text": "**Bis zu 5 Resturlaubstage** gehen ins nächste Jahr über und verfallen am 31. März."
}

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt text, Pflicht und nicht leer. Andere Felder werden abgelehnt. Zugangsdaten des Bots, Standardkanal und die Unterhaltung für die Antwort ergänzt connic, das Modell sieht davon nichts.

connector-payload.json
{
  "text": "Dein Laptop ist genehmigt. Die IT meldet sich wegen der Abholung bei dir."
}

Zustellung und Wiederholungen

Bittet Teams darum, langsamer zu senden, oder meldet es, dass es kurz nicht erreichbar ist, wartet connic und stellt die Nachricht erneut zu. Geht die Antwort von Teams verloren oder meldet Teams einen anderen Serverfehler, sendet connic die Nachricht nicht noch einmal. Prüfe dann die Unterhaltung. Die Runs der Verbindung zeigen jede Zustellung oder ihren Fehler.

Limits und Fehler

LimitWert
Antwort an TeamsTeams erwartet innerhalb weniger Sekunden eine Antwort. connic bestätigt jede Nachricht sofort und startet die Agenten danach. Die Antwort des Agenten kommt deshalb als eigene Nachricht.
Nachrichten an Teams7 pro Sekunde und 1.800 pro Stunde je Bot und Unterhaltung, von Microsoft vorgegeben. Bittet Teams darum, langsamer zu senden, wartet connic und stellt die Nachricht erneut zu.
Bot name30 Zeichen
Dateien in NachrichtenWerden weder heruntergeladen noch an den Agenten weitergegeben. Angaben dazu stehen nur in raw.
TenantNur der Tenant des Bots. Nachrichten aus anderen Tenants ignoriert connic.

connic prüft, ob jede Anfrage von Microsoft für deinen Bot kommt, und antwortet sonst mit 401. Ein Kontozugang lässt sich nicht speichern, wenn Microsoft Entra ID die Anmeldung des Bots ablehnt, etwa wegen eines falschen Clientgeheimnisses oder weil der Bot nicht für einen einzelnen Tenant angelegt ist. Eine Verbindung lässt sich nicht anlegen, solange die Einrichtung des Kontozugangs nicht abgeschlossen ist. Ist das Clientgeheimnis abgelaufen, schlagen Zustellungen fehl, bis du ein neues im Kontozugang einträgst. Eine Zustellung schlägt außerdem fehl, wenn Teams die Nachricht ablehnt, etwa weil die App im Team oder Chat nicht installiert ist, und wenn der Run nicht aus Teams kam und die Verbindung keinen Standardkanal hat.