---
title: "Start a new Message Session"
method: POST
path: "/domains/{domain}/users/{user}/messages"
tags: ["Messages"]
---

# Start a new Message Session

`POST /domains/{domain}/users/{user}/messages`

This is a good place to start with messaging if you do not already have a message session ID.

## Path parameters

- `domain` string, required — This is the main organization name. This is used to link resource to its group/tenant/organization/enterprise. Then using in path for GET you can set to "~" to use the domain name linked to your token/key instead of the domain name itself when reading for your own domain.
- `user` string, required — This is the main user extension for the user account. ~ can be used to mean "my account" which will extract the user from the token/key used for authentication.

## Request body

- object
  - `type` string, required
  - `message` string, required — This is the text that will be sent as the message
  - `destination` union, required — This is a single user or phonenumber for chat and SMS respectively. If sending to multiple recipients, then should be an array of users or phonenumbers
    - string — A single domain user or phonenumber
    - string[] — An array of domain users or phonenumbers in string format
  - `from-number` string — This is used only for SMS. This is the user's number used to send outbound for SMS
  - `data` string, nullable — This is used only for media chat or MMS. This is the base64 data of the media file to be sent
  - `mime-type` string
  - `size` integer, nullable — This is used only for media chat or MMS. This is the size in bytes of the media file being sent

## Response `200`

- Message
  - `id` union, required — This is the ID of the message
    - string
    - integer
  - `timestamp` 'YYYY-MM-DDTHH:MM:SS.ssZ', required — This is the time stamp that the formated via RFC 3339
  - `type` string, required
  - `domain` string, required — This is the main organization name. This is used to link resource to its group/tenant/organization/enterprise. ~ and * can be used alone in special cases to mean My Domain (~) and All Domains (\*).
  - `direction` string, required — This is the direction of the message. Either term for outbound or orig for inbound
  - `from-number` union — This is the SMS number the message came from. Is not set for chat messages
    - string
    - integer
  - `from-user-id` string, nullable, required — This is the User ID the message came from. Not set for offnet numbers
  - `from-video-attendee-id` string, nullable, required — This is the video attendee id the message came from if sent within a video call
  - `from-user-agent` string, nullable, required — This is the HTTP USER AGENT the message came from
  - `dialed` string, nullable, required — This is the number that this message is sent to. This can be comma seperated list of numbers if more than one in a group MMS session. Or null for chat sessions
  - `text` union, required — This is the text sent in the message
    - string
    - integer
    - boolean
    - object
    - number
  - `terminating-user-id` string, nullable, required — This is the receiving User ID of the message
  - `terminating-number` string, nullable, required — This is the number that this message is sent to. This can be comma seperated list of numbers if more than one in a group MMS session. Or null for chat sessions
  - `status` string, required — This is the status of the message
  - `video-instance-id` string, nullable — This is the video instance ID of the message if the message was sent from a video session.
  - `media-type` string, nullable, required — This is the media type of the message if applicable
  - `media-size` integer, nullable, required — This is the media size of the message if applicable
  - `deleted-datetime` 'YYYY-MM-DDTHH:MM:SS.ssZ' — This is the time stamp that the formated via RFC 3339
  - `messagesession-reciever-hostname` string, required — This is the receiver hostname for the message
  - `messagesession-id` string, required — This is the messagesession ID for this message
  - `messagesession-participants` string, nullable, required — This is the comma seperated participants of the messagesession associated with this message

## Other responses

- `400`
- `401`
- `404`

---

[API](https://skmtc.net/ns-api/apis/netsapiens-api-v2.md) · [All operations](https://skmtc.net/ns-api/apis/netsapiens-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ns-api/netsapiens-api-v2/versions/d37f65b5b886/schema)