{"openapi":"3.0.1","info":{"title":"Conversation API","description":"Provides methods for creating, retrieving, updating, and deleting\nconversations. Supports management of conversation participants—adding and\nremoving members—and typing indicators to signal real-time interaction\nwithin a conversation.","version":"1.0.1"},"servers":[{"url":"https://{region}-api.dotdigital.com","variables":{"region":{"description":"The Dotdigital region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"basicAuth":[]}],"paths":{"/cpaas/conversations/{conversationId}":{"get":{"summary":"Retrieves a conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}},{"name":"includeDeleted","in":"query","description":"Indicates whether deleted conversations should be returned","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"The requested conversation","headers":{"ETag":{"description":"A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE","schema":{"type":"string"}},"Last-Modified":{"description":"The date the conversation was last updated in ISO 8601 format","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"404":{"description":"The conversation was not found","content":{}}}},"put":{"summary":"Updates a conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}},{"name":"if-match","in":"header","description":"An optional ETag for optimistic concurrency control","required":false,"schema":{"type":"string"}}],"requestBody":{"description":"Detail of the conversation to update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdate"}}},"required":true},"responses":{"200":{"description":"The updated conversation","headers":{"ETag":{"description":"A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE","schema":{"type":"string"}},"Last-Modified":{"description":"The date the conversation was last updated in ISO 8601 format","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"400":{"description":"Validation issues were found","content":{}},"404":{"description":"The conversation was not found","content":{}},"409":{"description":"A conncurrency issue occured updating the conversation","content":{}},"412":{"description":"The specified 'if-match' header was not valid, refresh and retry","content":{}}},"x-codegen-request-body-name":"name"},"delete":{"summary":"Deletes a conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}},{"name":"if-match","in":"header","description":"An optional ETag for optimistic concurrency control","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Indicates successful deletetion of an conversation","content":{}},"404":{"description":"The conversation was not found","content":{}},"409":{"description":"A conncurrency issue occured deleting the conversation","content":{}},"412":{"description":"The specified 'if-match' header was not valid, refresh and retry","content":{}}}}},"/cpaas/conversations":{"get":{"summary":"Retrieves a list of conversations","parameters":[{"name":"scope","in":"query","description":"Defines the scope of the conversations to be returned - either all public conversations, ","required":false,"schema":{"type":"string","enum":["public","participant"]}},{"name":"profileId","in":"query","description":"Indicates whether only conversations the profile is a participant of should be returned","required":false,"schema":{"type":"string"}},{"name":"includeDeleted","in":"query","description":"Indicates whether deleted conversations should be returned","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"A list of matching conversations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationQueryResult"}}}}}}},"post":{"summary":"Creates a new conversation","requestBody":{"description":"Detail of the conversation to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreate"}}},"required":true},"responses":{"201":{"description":"The conversation was successfully created","headers":{"ETag":{"description":"A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE","schema":{"type":"string"}},"Last-Modified":{"description":"The date the conversation was last updated in ISO 8601 format","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"400":{"description":"Validation issues were found","content":{}},"409":{"description":"The conversation already exists","content":{}}},"x-codegen-request-body-name":"conversation"}},"/cpaas/conversations/{conversationId}/typing":{"post":{"summary":"Indicates that the caller is typing in this conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The request was accepted","content":{}}}},"delete":{"summary":"Indicates that the caller has stopped typing in this conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The request was accepted","content":{}}}}},"/cpaas/conversations/{conversationId}/participants":{"get":{"summary":"Retrieves the conversation participants","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The requested conversation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}}}}},"404":{"description":"The conversation was not found","content":{}}}},"post":{"summary":"Adds a list of participants to a conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The list of participants to add to the conversation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}}}},"required":true},"responses":{"201":{"description":"The participants were added","content":{}},"400":{"description":"Validation issues were found","content":{}},"404":{"description":"The conversation was not found","content":{}}},"x-codegen-request-body-name":"participants"},"delete":{"summary":"Deletes a list of participants from a conversation","parameters":[{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","description":"The profile ids of participants to remove from the conversation","required":true,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"204":{"description":"The list was accepted and valid participants will be removed","content":{}},"404":{"description":"The conversation was not found","content":{}}}}}},"components":{"schemas":{"ConversationCreate":{"required":["id","isPublic","name","roles"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation"},"name":{"type":"string","description":"The name of the conversation"},"description":{"type":"string","description":"The description of the conversation"},"roles":{"$ref":"#/components/schemas/Roles"},"isPublic":{"type":"boolean","description":"Determines whether the conversation is publically visible"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}},"messageScope":{"type":"string","description":"Indicates if a conversation is A2P or P2P","enum":["a2p","p2p"]}}},"ConversationUpdate":{"required":["name","roles"],"type":"object","properties":{"name":{"type":"string","description":"The name of the conversation"},"description":{"type":"string","description":"The description of the conversation"},"roles":{"$ref":"#/components/schemas/Roles"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation"},"name":{"type":"string","description":"The name of the conversation"},"description":{"type":"string","description":"The description of the conversation"},"roles":{"$ref":"#/components/schemas/Roles"},"isPublic":{"type":"boolean","description":"Determines whether the conversation is publically visible"},"messageScope":{"type":"string","description":"Indicates if a conversation is A2P or P2P","enum":["a2p","p2p"]},"_createdOn":{"type":"string","description":"The date (in UTC, ISO 8601 format) that the conversation was created","format":"date-time","readOnly":true},"_createdBy":{"type":"string","description":"The identity that created the conversation"},"_updatedOn":{"type":"string","description":"The date (in UTC, ISO 8601 format) that the conversation was last updated","format":"date-time","readOnly":true},"_updatedBy":{"type":"string","description":"The identity that created the conversation","readOnly":true}}},"ConversationQueryResult":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the conversation"},"name":{"type":"string","description":"The name of the conversation"},"description":{"type":"string","description":"The description of the conversation"},"roles":{"$ref":"#/components/schemas/Roles"},"isPublic":{"type":"boolean","description":"Determines whether it is publically visible"},"participantCount":{"type":"integer","description":"The total number of participants"},"latestSentEventId":{"type":"integer","description":"The eventId of the last message sent"},"messageScope":{"type":"string","description":"Indicates if a conversation is A2P or P2P","enum":["a2p","p2p"]},"_createdOn":{"type":"string","description":"The date (in UTC, ISO 8601 format) that the conversation was created","format":"date-time","readOnly":true},"_createdBy":{"type":"string","description":"The identity that created the conversation"},"_updatedOn":{"type":"string","description":"The date (in UTC, ISO 8601 format) that the conversation was last updated","format":"date-time","readOnly":true},"_updatedBy":{"type":"string","description":"The identity that created the conversation","readOnly":true}}},"Roles":{"required":["owner","participant"],"type":"object","properties":{"owner":{"$ref":"#/components/schemas/Privileges"},"participant":{"$ref":"#/components/schemas/Privileges"}},"description":"Describes the roles belonging to the conversation"},"Role":{"$ref":"#/components/schemas/Privileges"},"Privileges":{"required":["canAddParticipants","canRemoveParticipants","canSend"],"type":"object","properties":{"canSend":{"type":"boolean","description":"Determines whether the role assigned can send to the conversation"},"canAddParticipants":{"type":"boolean","description":"Determines whether the role assigned can add participants to the conversation"},"canRemoveParticipants":{"type":"boolean","description":"Determines whether the role assigned can remove participants from the conversation"}}},"Participant":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"The id of the conversation participant's profile"},"role":{"type":"string","description":"The role of the conversation participant","enum":["owner","participant"],"default":"participant"}}}},"parameters":{"conversationIdPathParameter":{"name":"conversationId","in":"path","description":"The id of the conversation","required":true,"schema":{"type":"string"}}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}},"x-readme":{"samples-languages":["curl","csharp","java","node","php","python","ruby"],"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true}}