---
title: "Manipulate conversation"
method: POST
path: "/inbox/v1/virtual-agent/conversations/{conversationId}"
tags: ["Inbox"]
---

# Manipulate conversation

`POST /inbox/v1/virtual-agent/conversations/{conversationId}`

## Request

- Base URL: `https://platform.hootsuite.com`
- URL: `https://platform.hootsuite.com/inbox/v1/virtual-agent/conversations/{conversationId}`
- Auth: OAuth 2
  - Authorization code: `https://platform.hootsuite.com/oauth2/auth`
  - Token URL: `https://platform.hootsuite.com/oauth2/token`

This allows you to manipulate the conversation in the same way you would when responding to a webhook request. You can
send a reply, add a topic, and/or hand off the conversation. Each property in the body is optional. If you only want to
send a message, you can send `{"sendMessage": {"text": "Hi!"}}`. If you want to apply a topic and complete, but not send
a message, you can, for example, send `{"applyTopics":["Spam"], "complete": "RESOLVED"}`.

Note that only topics that match a topic in the platform exactly (case insensitive) will be applied to the conversation.
Non-existing topics are ignored. Currently, no fuzzy matching will occur and typographical errors will result in a
non-existing topic.

The same applies to tags. Only tags that match a tag in the platform exactly (case
insensitive) will be applied to a specific message. Non-existing tags are ignored. You must specify the `messageId` when using the REST
API. The `messageId` is part of every `INBOUND_MESSAGE_RECEIVED` event.

If you want to send an attachment, you must first upload the attachment in a separate
call (`PUT /inbox/v1/virtual-agent/conversations/{conversationId}/attachments/{filename}`), and then use the file name when
sending the message (`{"sendMessage": {"attachment": ""}}`).

If the contact already has a value saved for the attribute definition with a particular alias, the update will be
ignored. If any of the attribute definitions are configured as CRM lookup values, a CRM lookup is performed after the
attributes are set. For the best performance, we recommend setting contact attributes along with the response to
indicate that the conversation is completed. Note that the virtual agent will not receive the new attributes from the
CRM response until the next `CONVERSATION_STARTED` or `CONVERSATION_DELEGATED` event is received for a conversation with
a contact.

## Path parameters

- `conversationId` string, required

## Request body

- ConversationManipulation
  - `indicateTyping` 'START' | 'STOP': Indicate whether you are typing
  - `sendMessages` Message1[]: The messages you want to send
    - `text` string
    - `attachment` string
  - `sendMessage` Message1: The messages you want to send
    - `text` string
    - `attachment` string
  - `applyTopics` string[]: The topics you want to apply to the conversation
  - `applyTags` string[]: The tag you want to apply to the latest message
  - `applyConversationNotes` object[]: The notes you want to apply to the conversation
    - `text` string
  - `setContactAttributes` object: The attributes you want to apply to the contact. The key should match "^[a-zA-Z0-9_]+$"
  - `complete` 'HANDOVER' | 'RESOLVED': Finish a conversation by handing it off to a human agent or by marking the conversation resolved

## Response `200`

Success

- object

## Other responses

- `400`: The request is malformed.
- `401`: Unauthorized: when using an invalid or expired access token.
- `404`: The conversation id does not exist or is no longer assigned to the virtual agent.

---

[API](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api.md) - [All operations](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/revisions/adac53bd28bb?raw)