Chat - Create Chat Thread

Servizio:
Communication
Versione API:
2025-03-15

Crea un thread di chat.

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

Parametri dell'URI

Nome In Necessario Tipo Descrizione
endpoint
 path True

string

Endpoint della risorsa di comunicazione di Azure.
api-version
 query True

string

Versione dell'API da richiamare.

Intestazione della richiesta

Nome Necessario Tipo Descrizione
Authorization True

string

Un token di accesso utente ACS (Servizi di comunicazione di Azure).
repeatability-request-id

string

Se specificato, il client indirizza che la richiesta è ripetibile; ovvero, che il client può effettuare la richiesta più volte con la stessa ripetibilità-Request-Id e ottenere una risposta appropriata senza che il server eseeseguono la richiesta più volte. Il valore di Repeatability-Request-Id è una stringa opaca che rappresenta un identificatore per la richiesta generato dal client, globalmente univoco per tutto il tempo. È consigliabile usare gli UUID versione 4 (casuale).

Corpo della richiesta

Nome Necessario Tipo Descrizione
topic True

string

Argomento del thread di chat.
metadata

object

Metadati contestuali per il thread. I metadati sono costituiti da coppie nome/valore. Le dimensioni totali di tutte le coppie di metadati possono essere fino a 1 KB.
participants

ChatParticipant[]

Partecipanti da aggiungere al thread di chat.
retentionPolicy ChatRetentionPolicy:

Criteri di conservazione dei dati per l'eliminazione automatica.

Risposte

Nome Tipo Descrizione
201 Created

CreateChatThreadResult

Thread creato, l'intestazione Location conterrà l'URL per il thread appena creato.
401 Unauthorized

CommunicationErrorResponse

Non autorizzato.
403 Forbidden

CommunicationErrorResponse

Vietato.
429 Too Many Requests

CommunicationErrorResponse

Troppe richieste.
Other Status Codes

CommunicationErrorResponse

Servizio non disponibile

Sicurezza

Authorization

Un token di accesso utente ACS (Servizi di comunicazione di Azure).

Tipo: apiKey
In: header

Esempio

Create chat thread
Create chat thread with repeatability request id header

Create chat thread

Esempio di richiesta

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

Risposta di esempio

Codice di stato:
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"
    }
  ]
}
Codice di stato:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
Codice di stato:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
Codice di stato:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
Codice di stato:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Create chat thread with repeatability request id header

Esempio di richiesta

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

Risposta di esempio

Codice di stato:
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"
    }
  ]
}
Codice di stato:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
Codice di stato:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
Codice di stato:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
Codice di stato:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Definizioni

Nome Descrizione
ChatParticipant

Partecipante del thread di chat.
ChatThreadProperties

Thread di chat.
CreateChatThreadRequest

Richiedere il payload per la creazione di un thread di chat.
CreateChatThreadResult

Risultato dell'operazione di creazione del thread di chat.
NoneRetentionPolicy

Nessun criterio di conservazione dei thread.
ThreadCreationDateRetentionPolicy

Criteri di conservazione dei thread in base alla data di creazione del thread.

ChatParticipant

Object

Partecipante del thread di chat.

Nome Tipo Descrizione
communicationIdentifier

CommunicationIdentifierModel

displayName

string

Nome visualizzato per il partecipante alla chat.
metadata

object

Metadati contestuali per il partecipante alla chat. I metadati sono costituiti da coppie nome/valore. Le dimensioni totali di tutte le coppie di metadati possono essere fino a 1 KB.
shareHistoryTime

string (date-time)

Ora da cui la cronologia delle chat viene condivisa con il partecipante. Il timestamp è in formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.

ChatThreadProperties

Object

Thread di chat.

Nome Tipo Descrizione
createdByCommunicationIdentifier

CommunicationIdentifierModel

createdOn

string (date-time)

Timestamp al momento della creazione del thread di chat. Il timestamp è in formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.
deletedOn

string (date-time)

Timestamp quando il thread di chat è stato eliminato. Il timestamp è in formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.
id

string

ID thread di chat.
metadata

object

Metadati contestuali per il thread. I metadati sono costituiti da coppie nome/valore. Le dimensioni totali di tutte le coppie di metadati possono essere fino a 1 KB.
retentionPolicy ChatRetentionPolicy:

Criteri di conservazione dei dati per l'eliminazione automatica.
topic

string

Argomento del thread di chat.

CreateChatThreadRequest

Object

Richiedere il payload per la creazione di un thread di chat.

Nome Tipo Descrizione
metadata

object

Metadati contestuali per il thread. I metadati sono costituiti da coppie nome/valore. Le dimensioni totali di tutte le coppie di metadati possono essere fino a 1 KB.
participants

ChatParticipant[]

Partecipanti da aggiungere al thread di chat.
retentionPolicy ChatRetentionPolicy:

Criteri di conservazione dei dati per l'eliminazione automatica.
topic

string

Argomento del thread di chat.

CreateChatThreadResult

Object

Risultato dell'operazione di creazione del thread di chat.

Nome Tipo Descrizione
chatThread

ChatThreadProperties

Thread di chat.
invalidParticipants

CommunicationError[]

I partecipanti che non sono stati aggiunti al thread di chat.

NoneRetentionPolicy

Object

Nessun criterio di conservazione dei thread.

Nome Tipo Descrizione
kind string:

none

Tipo di criteri di conservazione

ThreadCreationDateRetentionPolicy

Object

Criteri di conservazione dei thread in base alla data di creazione del thread.

Nome Tipo Descrizione
deleteThreadAfterDays

integer (int32)

Indica quanti giorni dopo la creazione del thread il thread verrà eliminato.
kind string:

threadCreationDate

Tipo di criteri di conservazione