---
title: "POST a single conversation message"
method: POST
path: "/v2/conversations"
tags: ["Conversation"]
---

# POST a single conversation message

`POST /v2/conversations`

## Request

- Base URL: `https://conversations.api.globalrelay.com/v2/conversations`
- URL: `https://conversations.api.globalrelay.com/v2/conversations/v2/conversations`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://iam-oauth2.globalrelay.com/oauth2/token`
- TypeScript: <https://skmtc.dev/globalrelay/apis/conversation-archiving-api/docs/v2/conversations/post.ts> (a function with typed inputs; its response is checked against the schema)

Represents conversation between several parties, eg.g IM messaging or threaded conversation over time

## Headers

- `X-SubType` string, required

## Request body

- CreateConversationPayload: One conversation object that will be converted into one conversation style EML
  - `requestInfo` RequestInfo, required: Top level information that must be included in every request payload.
    - `requestId` string, required: Client generated UUID for tracking purposes (A UUID specified by RFC4122).
  - `conversationOverview` ConversationOverview, required: Meta information to the conversation thread. Can be used for EML header section.
    - `conversationId` string, required: An unique ID for the conversation. Unique to the authorized application.
    - `initiatorName` string, required: Name of the conversation initiator
    - `initiatorEmail` string, required: E-mail of the conversation initiator
    - `title` string: Title of the conversation
    - `description` string: Description of the conversation
    - `isExternal` boolean: Flag for internal/external status. External - including participants from other companies. Internal - no external participants. Internal users only.
    - `isPrivate` boolean: Flag for private/public status. Public - anyone can join the channel/chat Private - by invites only
    - `initialParticipants` EventUser[]: IDs of all participants involved in the conversation during the downloading period. Including users has left the conversation.
      - `displayName` string, required: User name
      - `corporateEmail` string, required: User's corporate email
      - `phone` string: User's phone number
      - `companyName` string: User's company name
      - `userType` 'initiator' | 'initiatedOBO' | 'affectedUser' | 'recipient': Type of user. If not present then user is assumed to be recipient.
      - `identityType` 'Internal' | 'External' | 'Bot': Identity of user
    - `conversationProperties` ConversationProperty[]: Additional properties to describe the conversation.
      - `name` string, required: Property name. Flexible field allowing metadata to be added.
      - `value` string, required: Property value
      - `xheader` boolean: Defines if a xheader is to be created in the Archive for this conversation property. The displayed header name will be prefixed with "X-GR-OC-"
      - `hidden` boolean: If set to true the key value pair in the properties will not appear within the body of the EML.This property field should coincide with the xheader field set to true.
    - `subjectOverride` string: Add a custom subject for the message header.
  - `conversationEvents` ConversationEvent[]
    - `eventTime` integer: Time of the event in epoch milliseconds, must be between the year 1990 and current year + 1
    - `eventType` 'File_transfer' | 'Invitation' | 'Message' | 'Admin_event' | 'User_joined' | 'User_left' | 'Message_edited' | 'Message_deleted' | 'User_removed' | 'User_event' | 'Reaction' | 'Meeting_event' | 'Context_reply': This indicates the type of event that occurred in the conversation
    - `childEvents` ConversationEvent[]
    - `participants` EventUser[]
      - `displayName` string, required: User name
      - `corporateEmail` string, required: User's corporate email
      - `phone` string: User's phone number
      - `companyName` string: User's company name
      - `userType` 'initiator' | 'initiatedOBO' | 'affectedUser' | 'recipient': Type of user. If not present then user is assumed to be recipient.
      - `identityType` 'Internal' | 'External' | 'Bot': Identity of user
    - `content` Eventcontent
      - `textType` 'plain' | 'html' | 'markdown': Text type for the association for the message
      - `message` string, required: Depending on 'textType', this can be html, plain text or markdown.
    - `systemText` string: Additional system text that was shown to conversation participants.
    - `files` FileInfo[]
      - `filename` string, required: Name of the file
      - `fileKey` string, required: Id/key of the file used to create attachment.Should be the same fileKey as specified when sending to Files endpoint
      - `fileHref` string: HREF link to denote the external link to the file on the host provider platform
      - `isInlined` boolean: Defines if attachment should be inlined in the Archived EML body
      - `transcribable` boolean: Flags video/voice file as requiring transcription downstream, if enabled for feed.

## Response `200`

Successful Operation

- CreateConversationResponse: API responses
  - `reconciliationId` string, required: Unique ID assigned by API service for each request which can be used for reconcilliation reporting

## Other responses

- `202`: Accepted
- `400`: Bad Request. Request is not well-formed
- `405`: Method is not supported
- `413`: Request size exceeds the allowable limit
- `429`: Rate Limit for this endpoint has been exceeded. Check headers for more information.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/globalrelay/apis/conversation-archiving-api.md) - [All operations](https://skmtc.dev/globalrelay/apis/conversation-archiving-api/llms.txt) - [OpenAPI document](https://skmtc.dev/globalrelay/apis/conversation-archiving-api/revisions/fb17ee2102c3?raw)