Partager via

Chat - Create Chat Thread

Service:
Communication
Version d'API:
2025-03-15

Crée un fil de conversation.

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

Paramètres URI

Nom Dans Obligatoire Type Description
endpoint
 path True

string

Point de terminaison de la ressource Azure Communication.
api-version
 query True

string

Version de l’API à appeler.

En-tête de la demande

Nom Obligatoire Type Description
Authorization True

string

Jeton d’accès utilisateur ACS (Azure Communication Services).
repeatability-request-id

string

S’il est spécifié, le client indique que la requête est reproductible ; autrement dit, que le client peut effectuer la requête plusieurs fois avec la même répétabilité -Request-Id et récupérer une réponse appropriée sans que le serveur exécute la requête plusieurs fois. La valeur de la répétabilité -Request-Id est une chaîne opaque représentant une chaîne générée par le client, globalement unique pour tout le temps, identificateur de la requête. Il est recommandé d’utiliser les UUID de la version 4 (aléatoire).

Corps de la demande

Nom Obligatoire Type Description
topic True

string

Rubrique du fil de conversation.
metadata

object

Métadonnées contextuelles pour le thread. Les métadonnées se composent de paires nom/valeur. La taille totale de toutes les paires de métadonnées peut atteindre jusqu’à 1 Ko.
participants

ChatParticipant[]

Participants à ajouter au fil de conversation.
retentionPolicy ChatRetentionPolicy:

Stratégie de rétention des données pour la suppression automatique.

Réponses

Nom Type Description
201 Created

CreateChatThreadResult

Thread créé, l’en-tête Location contient l’URL du thread nouvellement créé.
401 Unauthorized

CommunicationErrorResponse

Non autorisée.
403 Forbidden

CommunicationErrorResponse

Interdit.
429 Too Many Requests

CommunicationErrorResponse

Trop de demandes.
Other Status Codes

CommunicationErrorResponse

Service non disponible.

Sécurité

Authorization

Jeton d’accès utilisateur ACS (Azure Communication Services).

Type: apiKey
Dans: header

Exemples

Create chat thread
Create chat thread with repeatability request id header

Create chat thread

Exemple de requête

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

{
  "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"
    }
  ]
}

Exemple de réponse

Code d’état:
201 
Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2
{
  "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"
    }
  ]
}
Code d’état:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
Code d’état:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
Code d’état:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
Code d’état:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Create chat thread with repeatability request id header

Exemple de requête

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

{
  "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"
    }
  ]
}

Exemple de réponse

Code d’état:
201 
Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2
{
  "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"
    }
  ]
}
Code d’état:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
Code d’état:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
Code d’état:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
Code d’état:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Définitions

Nom Description
ChatParticipant

Participant au fil de conversation.
ChatThreadProperties

Fil de conversation.
CreateChatThreadRequest

Charge utile de requête pour la création d’un thread de conversation.
CreateChatThreadResult

Résultat de l’opération de création d’un thread de conversation.
NoneRetentionPolicy

Aucune stratégie de rétention de thread.
ThreadCreationDateRetentionPolicy

Stratégie de rétention des threads basée sur la date de création de thread.

ChatParticipant

Object

Participant au fil de conversation.

Nom Type Description
communicationIdentifier

CommunicationIdentifierModel

displayName

string

Nom complet du participant de conversation.
metadata

object

Métadonnées contextuelles pour le participant de conversation. Les métadonnées se composent de paires nom/valeur. La taille totale de toutes les paires de métadonnées peut atteindre jusqu’à 1 Ko.
shareHistoryTime

string (date-time)

Heure à partir de laquelle l’historique des conversations est partagé avec le participant. L’horodatage est au format RFC3339 : yyyy-MM-ddTHH:mm:ssZ.

ChatThreadProperties

Object

Fil de conversation.

Nom Type Description
createdByCommunicationIdentifier

CommunicationIdentifierModel

createdOn

string (date-time)

Horodatage lorsque le thread de conversation a été créé. L’horodatage est au format RFC3339 : yyyy-MM-ddTHH:mm:ssZ.
deletedOn

string (date-time)

Horodatage lorsque le thread de conversation a été supprimé. L’horodatage est au format RFC3339 : yyyy-MM-ddTHH:mm:ssZ.
id

string

ID du thread de conversation.
metadata

object

Métadonnées contextuelles pour le thread. Les métadonnées se composent de paires nom/valeur. La taille totale de toutes les paires de métadonnées peut atteindre jusqu’à 1 Ko.
retentionPolicy ChatRetentionPolicy:

Stratégie de rétention des données pour la suppression automatique.
topic

string

Rubrique sur les threads de conversation.

CreateChatThreadRequest

Object

Charge utile de requête pour la création d’un thread de conversation.

Nom Type Description
metadata

object

Métadonnées contextuelles pour le thread. Les métadonnées se composent de paires nom/valeur. La taille totale de toutes les paires de métadonnées peut atteindre jusqu’à 1 Ko.
participants

ChatParticipant[]

Participants à ajouter au fil de conversation.
retentionPolicy ChatRetentionPolicy:

Stratégie de rétention des données pour la suppression automatique.
topic

string

Rubrique du fil de conversation.

CreateChatThreadResult

Object

Résultat de l’opération de création d’un thread de conversation.

Nom Type Description
chatThread

ChatThreadProperties

Fil de conversation.
invalidParticipants

CommunicationError[]

Les participants qui n’ont pas pu être ajoutés au fil de conversation.

NoneRetentionPolicy

Object

Aucune stratégie de rétention de thread.

Nom Type Description
kind string:

none

Type de stratégie de rétention

ThreadCreationDateRetentionPolicy

Object

Stratégie de rétention des threads basée sur la date de création de thread.

Nom Type Description
deleteThreadAfterDays

integer (int32)

Indique le nombre de jours après la création du thread que le thread sera supprimé.
kind string:

threadCreationDate

Type de stratégie de rétention