Chat - Create Chat Thread

Servicio:
Communication
Versión de la API:
2025-03-15

Crea una conversación de chat.

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

Parámetros de identificador URI

Nombre En Requerido Tipo Description
endpoint
 path True

string

Punto de conexión del recurso de Comunicación de Azure.
api-version
 query True

string

Versión de la API que se va a invocar.

Encabezado de la solicitud

Nombre Requerido Tipo Description
Authorization True

string

Un token de acceso de usuario de ACS (Azure Communication Services).
repeatability-request-id

string

Si se especifica, el cliente dirige que se puede repetir la solicitud; es decir, que el cliente puede realizar la solicitud varias veces con la misma repetibilidad:Request-Id y obtener una respuesta adecuada sin que el servidor ejecute la solicitud varias veces. El valor de repeatability-Request-Id es una cadena opaca que representa un identificador globalmente único para todo el tiempo generado por el cliente para la solicitud. Se recomienda usar LOS UUID de la versión 4 (aleatorios).

Cuerpo de la solicitud

Nombre Requerido Tipo Description
topic True

string

El tema del subproceso de chat.
metadata

object

Metadatos contextuales para el subproceso. Los metadatos constan de pares nombre-valor. El tamaño total de todos los pares de metadatos puede tener un tamaño de hasta 1 KB.
participants

ChatParticipant[]

Participantes que se agregarán al subproceso de chat.
retentionPolicy ChatRetentionPolicy:

Directiva de retención de datos para la eliminación automática.

Respuestas

Nombre Tipo Description
201 Created

CreateChatThreadResult

Subproceso creado, el encabezado Location contendrá la dirección URL del subproceso recién creado.
401 Unauthorized

CommunicationErrorResponse

Desautorizado.
403 Forbidden

CommunicationErrorResponse

Prohibido.
429 Too Many Requests

CommunicationErrorResponse

Demasiadas solicitudes.
Other Status Codes

CommunicationErrorResponse

Servicio no disponible.

Seguridad

Authorization

Un token de acceso de usuario de ACS (Azure Communication Services).

Tipo: apiKey
En: header

Ejemplos

Create chat thread
Create chat thread with repeatability request id header

Create chat thread

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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"
    }
  ]
}
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

Solicitud de ejemplo

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

Respuesta de muestra

status code:
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"
    }
  ]
}
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."
  }
}

Definiciones

Nombre Description
ChatParticipant

Participante del subproceso de chat.
ChatThreadProperties

Hilo de chat.
CreateChatThreadRequest

Solicitar carga para crear un subproceso de chat.
CreateChatThreadResult

Resultado de la operación de creación de subprocesos de chat.
NoneRetentionPolicy

No hay ninguna directiva de retención de subprocesos.
ThreadCreationDateRetentionPolicy

Directiva de retención de subprocesos basada en la fecha de creación del subproceso.

ChatParticipant

Object

Participante del subproceso de chat.

Nombre Tipo Description
communicationIdentifier

CommunicationIdentifierModel

displayName

string

Nombre para mostrar del participante del chat.
metadata

object

Metadatos contextuales para el participante del chat. Los metadatos constan de pares nombre-valor. El tamaño total de todos los pares de metadatos puede tener un tamaño de hasta 1 KB.
shareHistoryTime

string (date-time)

Hora desde la que se comparte el historial de chat con el participante. La marca de tiempo está en formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.

ChatThreadProperties

Object

Hilo de chat.

Nombre Tipo Description
createdByCommunicationIdentifier

CommunicationIdentifierModel

createdOn

string (date-time)

Marca de tiempo cuando se creó el subproceso de chat. La marca de tiempo está en formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.
deletedOn

string (date-time)

Marca de tiempo cuando se eliminó el subproceso de chat. La marca de tiempo está en formato RFC3339: yyyy-MM-ddTHH:mm:ssZ.
id

string

Identificador de subproceso de chat.
metadata

object

Metadatos contextuales para el subproceso. Los metadatos constan de pares nombre-valor. El tamaño total de todos los pares de metadatos puede tener un tamaño de hasta 1 KB.
retentionPolicy ChatRetentionPolicy:

Directiva de retención de datos para la eliminación automática.
topic

string

Tema del subproceso de chat.

CreateChatThreadRequest

Object

Solicitar carga para crear un subproceso de chat.

Nombre Tipo Description
metadata

object

Metadatos contextuales para el subproceso. Los metadatos constan de pares nombre-valor. El tamaño total de todos los pares de metadatos puede tener un tamaño de hasta 1 KB.
participants

ChatParticipant[]

Participantes que se agregarán al subproceso de chat.
retentionPolicy ChatRetentionPolicy:

Directiva de retención de datos para la eliminación automática.
topic

string

El tema del subproceso de chat.

CreateChatThreadResult

Object

Resultado de la operación de creación de subprocesos de chat.

Nombre Tipo Description
chatThread

ChatThreadProperties

Hilo de chat.
invalidParticipants

CommunicationError[]

Los participantes que no se pudieron agregar al subproceso de chat.

NoneRetentionPolicy

Object

No hay ninguna directiva de retención de subprocesos.

Nombre Tipo Description
kind string:

none

Tipo de directiva de retención

ThreadCreationDateRetentionPolicy

Object

Directiva de retención de subprocesos basada en la fecha de creación del subproceso.

Nombre Tipo Description
deleteThreadAfterDays

integer (int32)

Indica cuántos días después de la creación del subproceso se eliminará el subproceso.
kind string:

threadCreationDate

Tipo de directiva de retención