> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chat.voicebot.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Update conversation by ID

> Update a conversation.



## OpenAPI

````yaml api-reference/openapi.json patch /conversations/{id}
openapi: 3.0.3
info:
  version: 0.1.0
  title: Client API
servers:
  - url: https://1-some-client.some-server.healvi-chat/third-party/v1
security:
  - bearerAuth: []
paths:
  /conversations/{id}:
    patch:
      tags:
        - conversations
      summary: Update a conversation.
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/ConversationStatus'
                user_id:
                  description: >-
                    Optional ID of user which should be associated with this
                    conversation.
                  type: integer
                  nullable: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
components:
  schemas:
    ConversationStatus:
      description: Status of a conversation.
      type: string
      enum:
        - to-do
        - in-progress
        - done
    Conversation:
      description: |
        A conversation between an agent and a customer.
        Assignable to a user to mark who is actively managing the conversation.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        created_at:
          description: Datetime when profile was created.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        channel:
          $ref: '#/components/schemas/Channel'
        status:
          $ref: '#/components/schemas/ConversationStatus'
        snooze_until:
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        agent:
          $ref: '#/components/schemas/Agent'
        customer:
          $ref: '#/components/schemas/Customer'
        user:
          $ref: '#/components/schemas/User'
        latest_message:
          allOf:
            - $ref: '#/components/schemas/Message'
          nullable: true
        latest_customer_message:
          description: Contains the latest message from the customer, if available.
          allOf:
            - $ref: '#/components/schemas/Message'
          nullable: true
        last_customer_reply_from:
          description: >
            Date and time of the last message received from the customer. This
            value remains even if

            you delete the last customer message.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        latest_note:
          description: Contains the latest note written from business.
          allOf:
            - $ref: '#/components/schemas/Note'
          nullable: true
        unread_customer_messages_count:
          description: Number of messages from customer which do not have status "read".
          type: integer
        reply_until:
          description: >
            Indicates until when it's possible to send a (free form) reply to
            this conversation. If a datetime

            in the future is given,

            it should be possible to send a reply without errors (exception:
            WhatsApp, see below).

            If this field is null, a reply can only be sent if the user

            initiates a new conversation. The timing differs per channel.
            WhatsApp has the

            most complex rules on sending messages. Currently it's only possible
            to initiate business messages

            by using pre approved templates. Note: even when this field
            indicates that no reply is possible,

            you can still call the API to send a reply. You will then receive a
            message status update from the channel

            if the message could not be delivered.

            Important (WhatsApp): there is the special case when the business
            initiates a conversation (e.g. using the restart method).

            As soon as the message is sent, a reply_until value will be given
            from WhatsApp. The business will only be able to

            send more messages if the user replies something within the 24 hour
            window. So even though this field indicates

            that a reply would be possible, an error will be received when the
            business tries to send another message without

            user interaction. See the fields "reply_possible" and
            "customer_interaction_required".
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        reply_possible:
          description: >
            Flag to indicate if a (free form) reply to this conversation is
            possible. If true, all requirements

            should be met that a message without error can be sent. Use this
            flag to enable/disable your chat input field.

            The "reply_until" field can be used to show how much time is left
            until conversation expires.
          type: boolean
        customer_interaction_required:
          description: >
            Flag to indicate if a message from the customer is required. Typical
            used in combination with the "restart"

            endpoint. After restarting a conversation, the "reply_possible" flag
            will turn true as soon as the customer

            sends any message.
          type: boolean
    Channel:
      description: Type of messenger service.
      type: string
      enum:
        - bridge
        - whatsapp
        - widget
    Agent:
      description: |
        Represents an agent belonging to a messenger service.
        A business phone number registered on WhatsApp is an agent.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        channel:
          $ref: '#/components/schemas/Channel'
        display_id:
          type: string
          description: An unique identifier within a channel.
          example: 4915223567929
        name:
          type: string
          description: Name received from channel.
          example: John Doe
        in_sync:
          type: boolean
          description: >
            Indicates whether the agent is actually a connected agent (e.g. a
            WhatsApp number).

            In case of disconnecting a tenants service, this flag will turn
            false to keep conversations.

            You should not use this agent anymore to send messages as you will
            receive errors.
        unread_conversations_count:
          type: integer
          description: Number of conversation with at least one unread customer message.
    Customer:
      description: |
        Represents a customer using a messenger service.
        A person with a phone number registered on WhatsApp is a customer.
      type: object
      properties:
        id:
          type: integer
        channel:
          $ref: '#/components/schemas/Channel'
        display_id:
          type: string
          description: An unique identifier within a channel.
          example: 4915223567929
        name:
          type: string
          description: Name received from channel.
          example: John Doe
        profile:
          $ref: '#/components/schemas/Profile'
    User:
      description: |
        User from business which operates this app.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        name:
          type: string
        email:
          type: integer
          nullable: true
        roles:
          description: List of roles. "admin" has all permissions implicitly.
          type: array
          items:
            type: string
        permissions:
          description: List of permissions.
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
    Message:
      description: A message within a conversation.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        conversation_id:
          type: integer
          description: Foreign ID of related conversation.
        from:
          $ref: '#/components/schemas/MessageFrom'
        source:
          $ref: '#/components/schemas/MessageSource'
        user_id:
          description: Id of user who created this message.
          type: integer
          nullable: true
        contents:
          description: >
            A message can contain multiple contents when receiving.

            Usually it is just one item. For example when sending multiple

            contacts with WhatsApp, it will generate one message with multiple

            contacts within the contents array. When sending, only one item in
            the

            array is allowed.
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/TextMessageContent'
              - $ref: '#/components/schemas/ImageMessageContent'
              - $ref: '#/components/schemas/VideoMessageContent'
              - $ref: '#/components/schemas/AudioMessageContent'
              - $ref: '#/components/schemas/DocumentMessageContent'
              - $ref: '#/components/schemas/LocationMessageContent'
              - $ref: '#/components/schemas/ContactMessageContent'
            minLength: 1
        status:
          $ref: '#/components/schemas/MessageStatus'
        agent_reaction:
          description: String containing a single emoji.
          type: string
          nullable: true
        customer_reaction:
          description: String containing a single emoji.
          type: string
          nullable: true
        sent_at:
          description: Datetime when message was sent.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        reference:
          description: Reference of a message within the same conversation
          allOf:
            - $ref: '#/components/schemas/Message'
          nullable: true
        latest_error:
          description: Contains the latest error if something went wrong.
          allOf:
            - $ref: '#/components/schemas/MessageError'
          nullable: true
        whatsapp_campaign:
          description: >-
            If "source" is "whatsapp-campaign" then this will be the campaign
            which created this message.
          allOf:
            - $ref: '#/components/schemas/WhatsappCampaign'
          nullable: true
    Note:
      description: Note within a conversation. Only visible to business.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        conversation_id:
          type: integer
        text:
          description: Note content.
          type: string
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
    Profile:
      description: >
        Profile data of a customer. A profile can have many customers. A
        customer belongs to one profile.

        Can be used to connect a real person with multiple messengers (aka
        customers) to one profile.
      type: object
      properties:
        id:
          type: integer
        salutation:
          type: string
          enum:
            - formal_male
            - formal_female
            - informal
        name:
          type: string
          example: John Doe
        gender:
          type: string
          enum:
            - undisclosed
            - male
            - female
            - diverse
        blocked:
          type: boolean
          description: If a profile is blocked, receiving messages will be disabled.
        date_of_birth:
          type: string
          format: date-time
          nullable: true
          example: '1970-01-01'
        phone_number:
          description: Phone number in international format.
          type: string
          nullable: true
          example: '+4915224367929'
        email:
          type: string
          format: email
          nullable: true
        address:
          type: string
          nullable: true
        custom_1:
          description: >-
            One of five custom fields. Names of custom fields can be configured
            via settings.
          type: string
          nullable: true
        custom_2:
          type: string
          nullable: true
        custom_3:
          type: string
          nullable: true
        custom_4:
          type: string
          nullable: true
        custom_5:
          type: string
          nullable: true
        created_at:
          description: Datetime when profile was created.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
        updated_at:
          description: Datetime when profile was last updated.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
    MessageFrom:
      description: Who wrote the message.
      type: string
      enum:
        - system
        - agent
        - customer
    MessageSource:
      description: What triggered the message.
      type: string
      enum:
        - user
        - whatsapp-campaign
    TextMessageContent:
      description: Simple message content containing text.
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        content:
          description: The content of the text message.
          type: string
    ImageMessageContent:
      description: Message content containing an image.
      allOf:
        - $ref: '#/components/schemas/FileMessageContent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
            caption:
              description: Caption of image.
              type: string
              nullable: true
    VideoMessageContent:
      description: Message content containing a video.
      allOf:
        - $ref: '#/components/schemas/FileMessageContent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - video
            caption:
              description: Caption of video.
              type: string
              nullable: true
    AudioMessageContent:
      description: Message content containing an audio recording.
      allOf:
        - $ref: '#/components/schemas/FileMessageContent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - audio
            voice:
              description: True if audio is a voice recording.
              type: boolean
    DocumentMessageContent:
      description: Message content containing a document.
      allOf:
        - $ref: '#/components/schemas/FileMessageContent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - document
            filename:
              description: Name of document.
              type: string
              nullable: true
            caption:
              description: Caption of document.
              type: string
              nullable: true
    LocationMessageContent:
      description: Message content containing a GPS location.
      type: object
      properties:
        type:
          type: string
          enum:
            - location
        latitude:
          type: string
        longitude:
          type: string
        address:
          type: string
          nullable: true
        name:
          description: Name of the place.
          type: string
          nullable: true
        url:
          type: string
          nullable: true
    ContactMessageContent:
      description: Message content containing a contact.
      type: object
      required:
        - name
      properties:
        type:
          type: string
          enum:
            - contact
        name:
          type: object
          required:
            - formatted_name
            - first_name
          properties:
            formatted_name:
              type: string
            first_name:
              type: string
              nullable: true
            middle_name:
              type: string
              nullable: true
            last_name:
              type: string
              nullable: true
            prefix:
              type: string
              nullable: true
            suffix:
              type: string
              nullable: true
        birthday:
          type: string
          format: date
          nullable: true
          example: '1970-01-01T00:00:00.000Z'
        phones:
          type: array
          items:
            type: object
            properties:
              phone:
                type: string
              type:
                type: string
        emails:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
              type:
                type: string
        addresses:
          type: array
          items:
            type: object
            properties:
              street:
                type: string
              city:
                type: string
              state:
                type: string
              zip:
                type: string
              country:
                type: string
              country_code:
                type: string
              type:
                type: string
        org:
          type: object
          properties:
            company:
              type: string
            department:
              type: string
            title:
              type: string
    MessageStatus:
      description: >-
        Status of message. Created messages have not been sent yet via external
        API.
      type: string
      enum:
        - created
        - sent
        - delivered
        - read
        - error
    MessageError:
      description: Error description when something went wrong sending/receiving a message.
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        message_id:
          type: integer
          description: Foreign ID of related message.
        type:
          type: string
          enum:
            - status-update
            - other
        original_message:
          description: Error message from bridge or messenger service.
          type: string
        created_at:
          description: Datetime when error was created.
          type: string
          format: date-time
          nullable: true
          example: '2023-01-01T12:00:00Z'
    WhatsappCampaign:
      description: WhatsApp campaign (marketing).
      type: object
      properties:
        id:
          type: integer
          description: Internal ID.
        name:
          description: Name of campaign.
          type: string
    FileMessageContent:
      description: Base object for message content having a file.
      type: object
      properties:
        has_file:
          type: boolean
          enum:
            - true
        uuid:
          description: Unique UUID of file. Used to retrieve file data from server.
          type: string
        name:
          description: Name of file.
          nullable: true
        mime_type:
          description: Type of file.
          type: string
          example: audio/ogg
        size:
          description: Size of file in bytes.
          type: integer
        download_url:
          description: URL to directly download the file. Token still needed.
          type: string
        public_download_url:
          description: >-
            URL to directly download the file without a token. Use at your own
            risk.
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````