Skip to content
HeyX API

Add Correspondence Message

Required scope: correspondence:create

Use this endpoint to record a message exchanged with a contact (for example an SMS, email, or chat message from an integration such as Intercom). Each message is linked to a contact point — either a phone number or an email address — and is rendered as its own item on the contact’s timeline.

Provide exactly one contact point: phone (optionally with phoneCountryCodes) or email. Messages are grouped into a conversation thread by conversationExternalId, and ingestion is idempotent per conversation on messageExternalId: a repeated call with the same messageExternalId returns the existing message with created: false instead of creating a duplicate.

When integrationId is supplied it must reference an existing integration in the workspace; the message is then attributed to that integration (name and logo) on the timeline.

Generated Reference
POST /public-api/publicapi.v1.Correspondence/AddCorrespondenceMessage

Ingests a single inbound or outbound message into a contact conversation. Messages are deduplicated per conversation by message_external_id.

Request AddCorrespondenceMessageRequest
Response AddCorrespondenceMessageResponse

AddCorrespondenceMessageRequest

Field Type Description
integration_id optional string Optional source integration that produced this message. When set, the message is attributed to the integration (name/logo) in the timeline.
channel string Delivery channel, for example "sms", "email", or "chat".
direction string Message direction. Defaults to "inbound" when omitted.
phone optional string Contact point. Exactly one of phone or email is required. Accepts either a full international number such as "+31612345678" or a local/raw phone number such as "06 12345678".
phone_country_codes repeated string Optional ISO 3166-1 alpha-2 country codes to try when `phone` does not already include a leading "+" country code.
email optional string
body string Message content in the app rich-text token format.
author_label string Optional human-readable sender label, for example the sender's name.
subject string Optional subject line, mainly relevant for email.
occurred_at optional int64 Optional message timestamp (unix seconds). Defaults to the ingestion time.
conversation_external_id string Correlation with the source system. conversation_external_id groups messages into a thread; message_external_id makes ingestion idempotent.
message_external_id string

AddCorrespondenceMessageResponse

Field Type Description
conversation_id string
message_id string
created bool False when an idempotent replay matched an existing message.

Request

Section titled “Request”
{
  "integrationId": "6f434054-d242-4457-b61e-c7626ef95fa4",
  "channel": "sms",
  "direction": "inbound",
  "phone": "+31612345678",
  "body": "Hi, is my order ready?",
  "authorLabel": "Jane Doe",
  "conversationExternalId": "intercom-conv-9",
  "messageExternalId": "intercom-msg-123"
}

A local phone number can be supplied together with candidate country codes:

{
  "channel": "sms",
  "phone": "06 12345678",
  "phoneCountryCodes": ["NL"],
  "body": "Bericht ontvangen"
}

Response

Section titled “Response”
{
  "conversationId": "b3f0a4c1-2d5e-4a9b-9c77-1e2f3a4b5c6d",
  "messageId": "14d7d8d7-49de-42db-bb49-c835b274d63f",
  "created": true
}
HeyX API