Chat - Create Chat Thread

Referenz

Service:: Communication

API Version:: 2024-03-15-preview

Erstellt einen Chatthread.

POST {endpoint}/chat/threads?api-version=2024-03-15-preview

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
endpoint	path	True	string	Der Endpunkt der Azure Communication-Ressource.
api-version	query	True	string	Version der aufzurufenden API.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
Authorization	True	string	Ein ACS-Benutzerzugriffstoken (Azure Communication Services).
repeatability-request-id		string	Wenn angegeben, leitet der Client an, dass die Anforderung wiederholbar ist. Das heißt, dass der Client die Anforderung mehrmals mit derselben Repeatability-Request-ID ausführen und eine entsprechende Antwort erhalten kann, ohne dass der Server die Anforderung mehrmals ausführt. Der Wert von Repeatability-Request-Id ist eine undurchsichtige Zeichenfolge, die einen vom Client generierten, global eindeutigen bezeichner für die Anforderung darstellt. Es wird empfohlen, UUIDs der Version 4 (zufällig) zu verwenden.

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
topic	True	string	Das Thema des Chatthreads.
metadata		object	Kontextbezogene Metadaten für den Thread. Die Metadaten bestehen aus Name-Wert-Paaren. Die Gesamtgröße aller Metadatenpaare kann bis zu 1 KB betragen.
participants		ChatParticipant[]	Teilnehmer, die dem Chatthread hinzugefügt werden sollen.
retentionPolicy		ChatRetentionPolicy: ThreadCreationDateRetentionPolicy NoneRetentionPolicy	Datenaufbewahrungsrichtlinie für das automatische Löschen.

Antworten

Name	Typ	Beschreibung
201 Created	CreateChatThreadResult	Der erstellte Thread enthält die `Location` URL für den neu erstellten Thread.
401 Unauthorized	CommunicationErrorResponse	Nicht autorisiert.
403 Forbidden	CommunicationErrorResponse	Unzulässig.
429 Too Many Requests	CommunicationErrorResponse	Too many requests. (Zu viele Anforderungen.)
Other Status Codes	CommunicationErrorResponse	Service unavailable. (Dienst nicht verfügbar.)

Sicherheit

Authorization

Ein ACS-Benutzerzugriffstoken (Azure Communication Services).

Type: apiKey
In: header

Beispiele

Create chat thread

Create chat thread with repeatability request id header

Create chat thread

Sample Request

HTTP

POST https://contoso.westus.communications.azure.com/chat/threads?api-version=2024-03-15-preview

{
  "topic": "Lunch",
  "retentionPolicy": {
    "kind": "threadCreationDate",
    "deleteThreadAfterDays": 30
  },
  "participants": [
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
        }
      },
      "displayName": "Jane"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
        }
      },
      "displayName": "Alex"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a"
        }
      },
      "displayName": "Bob"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b"
        }
      },
      "displayName": "Peter"
    }
  ]
}

Sample Response

Status code:: 201

Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2

Response Body

{
  "chatThread": {
    "id": "19:uni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2",
    "topic": "Lunch",
    "createdOn": "2020-06-06T05:55:41.6460000Z",
    "createdByCommunicationIdentifier": {
      "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
      "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
      }
    },
    "retentionPolicy": {
      "kind": "threadCreationDate",
      "deleteThreadAfterDays": 30
    }
  },
  "invalidParticipants": [
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
      "code": "403",
      "message": "Permissions check failed"
    },
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
      "code": "404",
      "message": "Not found"
    }
  ]
}

Status code:: 401

{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}

Status code:: 403

{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}

Status code:: 429

{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}

Status code:: 503

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Create chat thread with repeatability request id header

Sample Request

HTTP

POST https://contoso.westus.communications.azure.com/chat/threads?api-version=2024-03-15-preview

{
  "topic": "Lunch",
  "participants": [
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
        }
      },
      "displayName": "Jane"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
        }
      },
      "displayName": "Alex"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a"
        }
      },
      "displayName": "Bob"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b"
        }
      },
      "displayName": "Peter"
    }
  ]
}

Sample Response

Status code:: 201

Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2

Response Body

{
  "chatThread": {
    "id": "19:uni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2",
    "topic": "Lunch",
    "createdOn": "2020-06-06T05:55:41.6460000Z",
    "createdByCommunicationIdentifier": {
      "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
      "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
      }
    }
  },
  "invalidParticipants": [
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
      "code": "403",
      "message": "Permissions check failed"
    },
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
      "code": "404",
      "message": "Not found"
    }
  ]
}

Status code:: 401

{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}

Status code:: 403

{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}

Status code:: 429

{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}

Status code:: 503

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Definitionen

Name	Beschreibung
ChatParticipant	Ein Teilnehmer des Chatthreads.
ChatThreadProperties	Chatthread
CreateChatThreadRequest	Anforderungsnutzlast zum Erstellen eines Chatthreads.
CreateChatThreadResult	Ergebnis des Vorgangs "Chatthread erstellen".
NoneRetentionPolicy	Keine Threadaufbewahrungsrichtlinie.
ThreadCreationDateRetentionPolicy	Threadaufbewahrungsrichtlinie basierend auf dem Threaderstellungsdatum.

ChatParticipant

Ein Teilnehmer des Chatthreads.

Name	Typ	Beschreibung
communicationIdentifier	CommunicationIdentifierModel
displayName	string	Anzeigename für den Chatteilnehmer.
metadata	object	Kontextbezogene Metadaten für den Chatteilnehmer. Die Metadaten bestehen aus Name-Wert-Paaren. Die Gesamtgröße aller Metadatenpaare kann bis zu 1 KB betragen.
shareHistoryTime	string	Zeit, ab der der Chatverlauf für den Teilnehmer freigegeben wird. Der Zeitstempel hat RFC3339 Format: `yyyy-MM-ddTHH:mm:ssZ`.

ChatThreadProperties

Chatthread

Name	Typ	Beschreibung
createdByCommunicationIdentifier	CommunicationIdentifierModel
createdOn	string	Der Zeitstempel, zu dem der Chatthread erstellt wurde. Der Zeitstempel hat RFC3339 Format: `yyyy-MM-ddTHH:mm:ssZ`.
deletedOn	string	Der Zeitstempel, zu dem der Chatthread gelöscht wurde. Der Zeitstempel hat RFC3339 Format: `yyyy-MM-ddTHH:mm:ssZ`.
id	string	Chatthread-ID.
metadata	object	Kontextbezogene Metadaten für den Thread. Die Metadaten bestehen aus Name-Wert-Paaren. Die Gesamtgröße aller Metadatenpaare kann bis zu 1 KB betragen.
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	Datenaufbewahrungsrichtlinie für das automatische Löschen.
topic	string	Chatthreadthema.

CreateChatThreadRequest

Anforderungsnutzlast zum Erstellen eines Chatthreads.

Name	Typ	Beschreibung
metadata	object	Kontextbezogene Metadaten für den Thread. Die Metadaten bestehen aus Name-Wert-Paaren. Die Gesamtgröße aller Metadatenpaare kann bis zu 1 KB betragen.
participants	ChatParticipant[]	Teilnehmer, die dem Chatthread hinzugefügt werden sollen.
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	Datenaufbewahrungsrichtlinie für das automatische Löschen.
topic	string	Das Thema des Chatthreads.

CreateChatThreadResult

Ergebnis des Vorgangs "Chatthread erstellen".

Name	Typ	Beschreibung
chatThread	ChatThreadProperties	Chatthread
invalidParticipants	CommunicationError[]	Die Teilnehmer, die dem Chatthread nicht hinzugefügt werden konnten.

NoneRetentionPolicy

Keine Threadaufbewahrungsrichtlinie.

Name	Typ	Beschreibung
kind	string: none	Aufbewahrungsrichtlinientyp

ThreadCreationDateRetentionPolicy

Threadaufbewahrungsrichtlinie basierend auf dem Threaderstellungsdatum.

Name	Typ	Beschreibung
deleteThreadAfterDays	integer	Gibt an, wie viele Tage nach der Threaderstellung der Thread gelöscht wird.
kind	string: threadCreationDate	Aufbewahrungsrichtlinientyp

Share via

Chat - Create Chat Thread

URI-Parameter

Anforderungsheader

Anforderungstext

Antworten

Sicherheit

Authorization

Beispiele

Create chat thread

Sample Request

Sample Response

Create chat thread with repeatability request id header

Sample Request

Sample Response

Definitionen

ChatParticipant

ChatThreadProperties

CreateChatThreadRequest

CreateChatThreadResult

NoneRetentionPolicy

ThreadCreationDateRetentionPolicy

Zusätzliche Ressourcen