Skip to main content
PATCH
/
conversations
/
{id}
Update a conversation.
curl --request PATCH \
  --url https://1-some-client.some-server.healvi-chat/third-party/v1/conversations/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "to-do",
  "user_id": 123
}'
{
  "id": 123,
  "created_at": "2023-01-01T12:00:00Z",
  "channel": "bridge",
  "status": "to-do",
  "snooze_until": "2023-01-01T12:00:00Z",
  "agent": {
    "id": 123,
    "channel": "bridge",
    "display_id": 4915223567929,
    "name": "John Doe",
    "in_sync": true,
    "unread_conversations_count": 123
  },
  "customer": {
    "id": 123,
    "channel": "bridge",
    "display_id": 4915223567929,
    "name": "John Doe",
    "profile": {
      "id": 123,
      "salutation": "formal_male",
      "name": "John Doe",
      "gender": "undisclosed",
      "blocked": true,
      "date_of_birth": "1970-01-01",
      "phone_number": "+4915224367929",
      "email": "jsmith@example.com",
      "address": "<string>",
      "custom_1": "<string>",
      "custom_2": "<string>",
      "custom_3": "<string>",
      "custom_4": "<string>",
      "custom_5": "<string>",
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z"
    }
  },
  "user": {
    "id": 123,
    "name": "<string>",
    "email": 123,
    "roles": [
      "<string>"
    ],
    "permissions": [
      "<string>"
    ],
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  },
  "latest_message": {
    "id": 123,
    "conversation_id": 123,
    "from": "system",
    "source": "user",
    "user_id": 123,
    "contents": [
      {
        "type": "text",
        "content": "<string>"
      }
    ],
    "status": "created",
    "agent_reaction": "<string>",
    "customer_reaction": "<string>",
    "sent_at": "2023-01-01T12:00:00Z",
    "reference": {},
    "latest_error": {
      "id": 123,
      "message_id": 123,
      "type": "status-update",
      "original_message": "<string>",
      "created_at": "2023-01-01T12:00:00Z"
    },
    "whatsapp_campaign": {
      "id": 123,
      "name": "<string>"
    }
  },
  "latest_customer_message": {
    "id": 123,
    "conversation_id": 123,
    "from": "system",
    "source": "user",
    "user_id": 123,
    "contents": [
      {
        "type": "text",
        "content": "<string>"
      }
    ],
    "status": "created",
    "agent_reaction": "<string>",
    "customer_reaction": "<string>",
    "sent_at": "2023-01-01T12:00:00Z",
    "reference": {},
    "latest_error": {
      "id": 123,
      "message_id": 123,
      "type": "status-update",
      "original_message": "<string>",
      "created_at": "2023-01-01T12:00:00Z"
    },
    "whatsapp_campaign": {
      "id": 123,
      "name": "<string>"
    }
  },
  "last_customer_reply_from": "2023-01-01T12:00:00Z",
  "latest_note": {
    "id": 123,
    "conversation_id": 123,
    "text": "<string>",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  },
  "unread_customer_messages_count": 123,
  "reply_until": "2023-01-01T12:00:00Z",
  "reply_possible": true,
  "customer_interaction_required": true
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
integer
required

Body

application/json
​
status
enum<string>

Status of a conversation.

Available options:
to-do,
in-progress,
done
​
user_id
integer | null

Optional ID of user which should be associated with this conversation.

Response

200 - application/json

Success

A conversation between an agent and a customer. Assignable to a user to mark who is actively managing the conversation.

​
id
integer

Internal ID.

​
created_at
string<date-time> | null

Datetime when profile was created.

Example:

"2023-01-01T12:00:00Z"

​
channel
enum<string>

Type of messenger service.

Available options:
bridge,
whatsapp,
widget
​
status
enum<string>

Status of a conversation.

Available options:
to-do,
in-progress,
done
​
snooze_until
string<date-time> | null
Example:

"2023-01-01T12:00:00Z"

​
agent
object

Represents an agent belonging to a messenger service. A business phone number registered on WhatsApp is an agent.

​
customer
object

Represents a customer using a messenger service. A person with a phone number registered on WhatsApp is a customer.

​
user
object

User from business which operates this app.

​
latest_message
object

A message within a conversation.

​
latest_customer_message
object

Contains the latest message from the customer, if available. A message within a conversation.

​
last_customer_reply_from
string<date-time> | null

Date and time of the last message received from the customer. This value remains even if you delete the last customer message.

Example:

"2023-01-01T12:00:00Z"

​
latest_note
object

Contains the latest note written from business. Note within a conversation. Only visible to business.

​
unread_customer_messages_count
integer

Number of messages from customer which do not have status "read".

​
reply_until
string<date-time> | null

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".

Example:

"2023-01-01T12:00:00Z"

​
reply_possible
boolean

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.

​
customer_interaction_required
boolean

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.