Twilio Conversation Summaries API

openapi: 3.2.0
info:
  title: Twilio Memory Conversation Summaries API
  description: APIs for managing memory stores, profiles, and conversational intelligence capabilities.
  version: '1.0'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-twilio:
    apiStandards: v1.0
servers:
- url: https://memory.twilio.com
security:
- accountSid_authToken: []
tags:
- name: ConversationSummaries
  description: Conversation summaries are high-level recaps automatically generated from conversations that run through Conversation Orchestrator.
paths:
  /v1/Stores/{storeId}/Profiles/{profileId}/ConversationSummaries:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/ProfileId'
    x-twilio:
      defaultOutputProperties:
      - summaries
      pathType: list
    get:
      operationId: ListProfileConversationSummaries
      summary: List Conversation Summaries
      description: Retrieve a paginated list of conversation summaries for a specific profile. Supports response compression for large datasets.
      tags:
      - ConversationSummaries
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/AcceptEncoding'
      responses:
        '200':
          description: A list of conversation summaries for the profile.
          headers:
            Content-Encoding:
              $ref: '#/components/headers/ContentEncoding'
            Canonical-Profile-Id:
              $ref: '#/components/headers/Canonical-Profile-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  summaries:
                    type: array
                    maxItems: 50
                    items:
                      $ref: '#/components/schemas/SummaryInfo'
                  meta:
                    $ref: '#/components/schemas/ObservationsMeta'
              example:
                summaries:
                - id: mem_summary_00000000000000000000000001
                  conversationId: conv_conversation_00000000000000000000000000
                  content: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
                  source: conversational_intelligence
                  occurredAt: '2025-01-15T10:30:00Z'
                  createdAt: '2025-01-15T10:30:45Z'
                  updatedAt: '2025-01-15T10:30:45Z'
                - id: mem_summary_00000000000000000000000002
                  conversationId: conv_conversation_00000000000000000000000000
                  content: 'Customer: ''I love the new feature you added.'' Agent: ''Thank you for the feedback, we''re glad you''re enjoying it.'''
                  source: summary_operator
                  occurredAt: '2025-01-15T11:15:00Z'
                  createdAt: '2025-01-15T11:15:30Z'
                  updatedAt: '2025-01-15T11:15:30Z'
                meta:
                  pageSize: 2
                  nextToken: eyJlYXN0ZXIiOiJlZ2cifQ
        '301':
          $ref: '#/components/responses/MovedPermanently'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: CreateProfileConversationSummary
      summary: Create Conversation Summaries
      description: Create one or more conversation summaries associated with the specified profile. Supports both single summary creation and batch creation of up to 10 summaries. Supports request compression for large batch operations and response compression for the response. All summaries will be automatically indexed for semantic search capabilities. The content summary can be up to 4KB in length. Each summary will be created with a unique ID in Twilio Type ID (TTID) format.
      tags:
      - ConversationSummaries
      parameters:
      - $ref: '#/components/parameters/AcceptEncoding'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSummariesRequest'
            examples:
              Single Summary:
                value:
                  summaries:
                  - conversationId: conv_conversation_00000000000000000000000000
                    content: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
                    source: conversational_intelligence
                    occurredAt: '2025-01-15T15:00:00Z'
      responses:
        '202':
          description: Conversation summary creation accepted and is being processed.
          headers:
            Content-Encoding:
              $ref: '#/components/headers/ContentEncoding'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummariesCreatedResponse'
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/Stores/{storeId}/Profiles/{profileId}/ConversationSummaries/{summaryId}:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/ProfileId'
    - $ref: '#/components/parameters/SummaryId'
    x-twilio:
      pathType: instance
    get:
      operationId: FetchProfileConversationSummary
      summary: Retrieve Conversation Summary
      description: Retrieve a specific conversation summary by its ID for the given profile.
      tags:
      - ConversationSummaries
      responses:
        '200':
          description: Conversation summary retrieved successfully.
          headers:
            Canonical-Profile-Id:
              $ref: '#/components/headers/Canonical-Profile-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryInfo'
              examples:
                Summary Type:
                  value:
                    id: mem_summary_00000000000000000000000001
                    conversationId: conv_conversation_00000000000000000000000000
                    content: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
                    source: conversational_intelligence
                    occurredAt: '2025-01-15T14:30:00Z'
                    createdAt: '2025-01-15T10:30:45Z'
                    updatedAt: '2025-01-15T10:30:45Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: PatchProfileConversationSummary
      summary: Update Conversation Summary
      description: Partially update a specific conversation summary by its ID. Only provided fields will be updated. The updated timestamp will be automatically set. This allows for selective updates without needing to provide all fields.
      tags:
      - ConversationSummaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummaryCorePatch'
            examples:
              Update content only:
                value:
                  content: 'Updated: Customer discussed billing concerns and expressed complete satisfaction with the comprehensive resolution provided during this conversation.'
              Update source and occurredAt:
                value:
                  source: summary_followup
                  occurredAt: '2025-01-15T16:30:00Z'
      responses:
        '202':
          description: Conversation summary update accepted and is being processed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 255
                    example: Conversation summary update accepted
                required:
                - message
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: DeleteProfileConversationSummary
      summary: Delete Conversation Summary
      description: Delete a specific conversation summary by its ID. This action is irreversible.
      tags:
      - ConversationSummaries
      responses:
        '202':
          description: Conversation summary deletion accepted and is being processed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 255
                    example: Conversation summary deletion accepted
                required:
                - message
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    CreateSummariesRequest:
      type: object
      description: Request payload for creating one or more conversation summaries. Supports creation of up to 10 summaries.
      properties:
        summaries:
          type: array
          description: Array of summaries to create in a single batch operation.
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/SummaryCore'
      required:
      - summaries
      additionalProperties: false
    TwilioError:
      type: object
      additionalProperties: false
      maxProperties: 10
      description: A generic error object communicating client and server side API errors.
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 999999
          description: The Twilio error code.
          format: int32
        message:
          type: string
          maxLength: 1024
          description: A human readable message describing the error.
        more_info:
          type: string
          description: A URL to a [Twilio error directory](https://www.twilio.com/docs/api/errors) page with more information about the error code.
        status:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code for the error.
          format: int32
      example:
        code: 21614
        message: The address specified in the request is not a valid phone number.
        more_info: https://www.twilio.com/docs/api/errors/21614
        status: 400
    SummaryID:
      type: string
      description: A unique identifier for the summary using Twilio Type ID (TTID) format.
      pattern: ^mem_summary_[0-7][0-9a-z]{25}$
      example: mem_summary_00000000000000000000000000
    ConversationID:
      type: string
      description: A unique identifier for the conversation using Twilio Type ID (TTID) format.
      pattern: ^conv_conversation_[0-7][0-9a-z]{25}$
      example: conv_conversation_00000000000000000000000000
    SummaryCorePatch:
      type: object
      description: Core mutable properties for updating summary objects. All fields are optional for PATCH operations.
      properties:
        source:
          type: string
          description: The source system that generated the summary. Allows letters, numbers, spaces, periods, underscores, hyphens, and forward slashes.
          maxLength: 100
          pattern: ^[a-zA-Z0-9 _./-]+$
          example: conversations
        content:
          type: string
          description: The main content of the summary.
          minLength: 1
          maxLength: 4096
          example: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
        occurredAt:
          type: string
          format: date-time
          description: The timestamp when the summary was originally created. If not provided, defaults to the time the summary was received.
          example: '2025-01-15T10:15:30Z'
        conversationId:
          $ref: '#/components/schemas/ConversationID'
    SummaryInfo:
      type: object
      description: A summary memory derived from conversations.
      properties:
        source:
          type: string
          description: The source system that generated the summary. Allows letters, numbers, spaces, periods, underscores, hyphens, and forward slashes.
          maxLength: 100
          pattern: ^[a-zA-Z0-9 _./-]+$
          example: conversations
        content:
          type: string
          description: The main content of the summary.
          minLength: 1
          maxLength: 4096
          example: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
        occurredAt:
          type: string
          format: date-time
          description: The timestamp when the summary was originally created.
          example: '2025-01-15T10:15:30Z'
        conversationId:
          $ref: '#/components/schemas/ConversationID'
        id:
          $ref: '#/components/schemas/SummaryID'
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the summary was created.
          example: '2025-01-15T10:30:45Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the summary was last updated.
          example: '2025-01-15T10:30:45Z'
      required:
      - content
      - occurredAt
      - id
      - updatedAt
      - createdAt
      - conversationId
    SummariesCreatedResponse:
      type: object
      description: Response for batch summary creation.
      properties:
        message:
          type: string
          description: Confirmation message for the operation.
          minLength: 1
          maxLength: 255
          example: Summaries creation accepted
      required:
      - message
    SummaryCore:
      type: object
      description: Core mutable properties for creating summary objects.
      properties:
        source:
          type: string
          description: The source system that generated the summary. Allows letters, numbers, spaces, periods, underscores, hyphens, and forward slashes.
          maxLength: 100
          pattern: ^[a-zA-Z0-9 _./-]+$
          example: conversations
        content:
          type: string
          description: The main content of the summary.
          minLength: 1
          maxLength: 4096
          example: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
        occurredAt:
          type: string
          format: date-time
          description: The timestamp when the summary was originally created.
          example: '2025-01-15T10:15:30Z'
        conversationId:
          $ref: '#/components/schemas/ConversationID'
      required:
      - content
      - conversationId
      - occurredAt
    ObservationsMeta:
      type: object
      properties:
        key:
          type: string
          maxLength: 64
          description: 'The key of the list property contains the actual data items.

            This enables programmatic iteration over paginated results.

            '
          example: observations
        pageSize:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
        nextToken:
          type: string
          minLength: 1
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
        previousToken:
          type: string
          minLength: 1
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20500
            message: Internal Server Error
            more_info: https://www.twilio.com/docs/api/errors/20500
            status: 500
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 403
            message: Permission to access resource denied
            more_info: https://www.twilio.com/docs/api/errors/403
            status: 403
    PermanentRedirect:
      description: This resource has moved.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            - uri
            properties:
              message:
                type: string
                default: This resource has moved.
                example: This resource has moved.
                maxLength: 255
              uri:
                type: string
                example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
                maxLength: 2048
            maxProperties: 2
      headers:
        Canonical-Profile-Id:
          $ref: '#/components/headers/Canonical-Profile-Id'
        Location:
          $ref: '#/components/headers/Location'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20404
            message: Not Found
            more_info: https://www.twilio.com/docs/api/errors/20404
            status: 404
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20003
            message: Failed to complete request due to lack of authentication credentials
            more_info: https://www.twilio.com/docs/api/errors/20003
            status: 401
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20503
            message: Service Unavailable
            more_info: https://www.twilio.com/docs/api/errors/20503
            status: 503
    TooManyRequests:
      description: This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20429
            message: Too many requests. Please retry according to the Retry-After response header.
            more_info: https://www.twilio.com/docs/api/errors/20429
            status: 429
      headers:
        Retry-After:
          description: The amount of time in seconds that the customer should wait before issuing a new request towards the API.
          schema:
            type: string
            pattern: ^[0-9]+$
    MovedPermanently:
      description: This resource has moved.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            - uri
            properties:
              message:
                type: string
                default: This resource has moved.
                example: This resource has moved.
                maxLength: 255
              uri:
                type: string
                example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
                maxLength: 2048
            maxProperties: 2
      headers:
        Canonical-Profile-Id:
          $ref: '#/components/headers/Canonical-Profile-Id'
        Location:
          $ref: '#/components/headers/Location'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 400
            message: Failed to complete request due to a bad request
            more_info: https://www.twilio.com/docs/api/errors/400
            status: 400
  parameters:
    ConversationId:
      name: conversationId
      in: query
      required: false
      description: Filter by conversation ID. Returns only items associated with the specified conversation.
      schema:
        $ref: '#/components/schemas/ConversationID'
    StoreId:
      name: storeId
      in: path
      required: true
      description: A unique Memory Store ID using Twilio Type ID (TTID) format
      schema:
        type: string
        pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
        example: mem_store_00000000000000000000000000
    ProfileId:
      name: profileId
      in: path
      required: true
      description: The unique identifier for the profile using Twilio Type ID (TTID) format.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      description: Compression algorithm used for the request body (e.g., gzip, deflate, br)
      schema:
        type: string
        enum:
        - gzip
        - deflate
        - br
        - compress
        example: gzip
    PageToken:
      name: pageToken
      in: query
      required: false
      description: The token for the page of results to retrieve.
      schema:
        type: string
        maxLength: 4096
    PageSize:
      name: pageSize
      in: query
      required: false
      description: The maximum number of items to return per page, maximum of 1000.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 1000
    AcceptEncoding:
      name: Accept-Encoding
      in: header
      required: false
      description: Compression algorithms supported by the client (e.g., gzip, deflate, br)
      schema:
        type: string
        maxLength: 200
        pattern: ^[a-zA-Z0-9, .-]*$
        example: gzip, deflate, br
    SummaryId:
      name: summaryId
      in: path
      description: The summary ID.
      required: true
      schema:
        $ref: '#/components/schemas/SummaryID'
  headers:
    Location:
      description: The URL of the new location for the resource.
      schema:
        type: string
        format: uri
        example: https:///memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
        description: The URL of the new location for the resource.
    Canonical-Profile-Id:
      description: The canonical profile ID associated with the requested resource. If provided, this header indicates that the requested profile is merged to the canonical profile ID.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
        description: The canonical profile ID.
    ContentEncoding:
      description: The compression algorithm used for the response body
      schema:
        type: string
        enum:
        - gzip
        - deflate
        - br
        - compress
        example: gzip
  securitySchemes:
    basic_apikey_or_accountsid:
      scheme: basic
      type: http
      description: This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing.
    accountSid_authToken:
      scheme: basic
      type: http