# Receive message

Receive a message.
This is different from a normal `/interactions` creation because
it creates the interaction and also performs associated "inbound message"
actions:
- if the message is an email sent to an email address configured as
"unmonitored", it will autorespond that the email was not received because
it was sent to an "unmonitored address".
- it will publish a taskrouter task for inbound interactions (either
`handleInboundInteraction` or `handleUnboundInboundInteraction`).

Endpoint: POST /communicator/receive
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Request fields (application/json):

  - `channel` (string)
    The channel by which an interaction occurs.
    Enum: "fax", "gui", "document"

  - `content` (object)
    The content and attributes of the message sent. Normally in JSON format.

  - `channel` (string)
    The channel by which an interaction occurs—always `voice` for `VoiceInteraction`
    Enum: "voice"

  - `content` (object)

  - `content.from` (string)
    An E.164 formatted phone number—a phone number prefixed with a `+` and
a country code. (Note that in the United States this is `+1`)
    Example: +12024561111

  - `holdDuration` (number)
    The amount of time the inbound caller was on hold before
speaking to an agent, in seconds. `null` if the caller wasn't on
hold.

  - `isAutodialed` (boolean)
    `true` if an autodialed call. If no value is passed, we'll assume
isAutodialed=`false`—meaning a manual call was performed.
For more information on why this is important reference the
Telephone Consumer Protection Act (TCPA).

  - `recordingConsentGiven` (boolean)
    `true` if the borrower has given consent to record the call.

  - `recordingDuration` (integer)
    The duration of the recording of this voice call in seconds, or `null` if there
is no recording.

  - `recordingStartedAt` (string)
    The date-time at which the recording of this voice call started, or `null`
if there is no recording.

  - `twilioConferenceFriendlyName` (string)
    The Twilio conference friendly name for this voice interaction.

  - `twilioConferenceSid` (string)
    The Twilio conference SID for this voice interaction.

  - `voicemailDuration` (integer)
    The duration of the voicemail of this voice call in seconds, or `null` if there
is no voicemail.

  - `voicemailStartedAt` (string)
    The date-time at which the voicemail left for this call started, or `null`
if there is no voicemail.

  - `channel` (string)
    The channel by which an interaction occurs—always `email` for `EmailInteraction`.
    Enum: "email"

  - `emailInReplyTo` (string)
    The contents of the `In-Reply-To` header, the unique [RFC5322
email message
ID](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4)
associated with the email being replied to. `null` if the header
wasn't present in the email.

  - `emailMessageId` (string)
    The contents of the `Message-ID` header, the unique [RFC5322
email message
ID](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4)
associated with this email. `null` if the header wasn't present
in the email.

  - `emailReferences` (string)
    The contents of the `References` header, a structured string of
[RFC5322 email message
IDs](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4) that
identify the messages making up the email thread. `null` if the
header wasn't present in the email.

  - `channel` (string)
    The channel by which an interaction occurs—always `text` for `TextInteraction``.
    Enum: "text"

  - `channel` (string)
    The channel by which an interaction occurs—always `chat` for `ChatInteraction`
    Enum: "chat"

  - `channel` (string)
    The channel by which an interaction occurs—always `mail` for `MailInteraction`
    Enum: "mail"

  - `mailIsCertified` (boolean)
    Whether or not this mail interaction is sent as [USPS Certified
Mail](https://faq.usps.com/s/article/Certified-Mail-The-Basics). Certified
mail provides proof of mailing and has more granular tracking
events, but incurs additional cost. Please refer to your order
form for more pricing information.
NOTE: Sending as certified mail is currently only supported for
the following subjects:
- `loanRightToCurePersonalUnsecured`
- `loanRightToCurePersonalUnsecuredColorado`
- `loanRightToCurePersonalUnsecuredDC`
- `loanRightToCurePersonalUnsecuredIowa`
- `loanRightToCurePersonalUnsecuredKansas`
- `loanRightToCurePersonalUnsecuredMaine`
- `loanRightToCurePersonalUnsecuredMissouri`
- `loanRightToCurePersonalUnsecuredSouthCarolina`
- `loanRightToCurePersonalUnsecuredWestVirginia`
- `loanRightToCurePersonalUnsecuredWisconsin`

  - `mailNumberOfPages` (integer)

## Response 200 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (any)

  - `data.channel` (string)
    The channel by which an interaction occurs.
    Enum: "fax", "gui", "document"

  - `data.content` (object)
    The content and attributes of the message sent. Normally in JSON format.

  - `data.channel` (string)
    The channel by which an interaction occurs—always `voice` for `VoiceInteraction`
    Enum: "voice"

  - `data.content` (object)

  - `data.content.from` (string)
    An E.164 formatted phone number—a phone number prefixed with a `+` and
a country code. (Note that in the United States this is `+1`)
    Example: +12024561111

  - `data.holdDuration` (number)
    The amount of time the inbound caller was on hold before
speaking to an agent, in seconds. `null` if the caller wasn't on
hold.

  - `data.inboundCallAcceptedBy` (object)

  - `data.inboundCallAcceptedBy.descriptor` (string)
    Short description of the user who performed the action.
Different systems may have different data available for a given user. The descriptor
gives the best available short description of the user. It prefers names, then email addresses,
then related IDs.
e.g.,
- "Borrower Tim Jones"
- "Borrower BO-ABCD-1234"
- "Peach Service User"
- "Agent Abigail Smith"
- "Agent bob@acme.com"
- "Agent EM-ABCD-1234"
    Example: Agent bob@acme.com

  - `data.inboundCallAcceptedBy.employee` (object)

  - `data.inboundCallAcceptedBy.employee.id` (string)
    The employee's ID

  - `data.inboundCallAcceptedBy.id` (string)
    The unique identifier of the user who performed the action.

  - `data.inboundCallAcceptedBy.name` (string)
    The name of the user who performed the action.

  - `data.inboundCallAcceptedBy.userType` (string)
    The type of the user.
    Enum: "agent", "borrower", "service"

  - `data.isAutodialed` (boolean)
    `true` if an autodialed call. If no value is passed, we'll assume
isAutodialed=`false`—meaning a manual call was performed.
For more information on why this is important reference the
Telephone Consumer Protection Act (TCPA).

  - `data.recordingConsentGiven` (boolean)
    `true` if the borrower has given consent to record the call.

  - `data.recordingDuration` (integer)
    The duration of the recording of this voice call in seconds, or `null` if there
is no recording.

  - `data.recordingStartedAt` (string)
    The date-time at which the recording of this voice call started, or `null`
if there is no recording.

  - `data.twilioConferenceFriendlyName` (string)
    The Twilio conference friendly name for this voice interaction.

  - `data.twilioConferenceSid` (string)
    The Twilio conference SID for this voice interaction.

  - `data.voicemailDuration` (integer)
    The duration of the voicemail of this voice call in seconds, or `null` if there
is no voicemail.

  - `data.voicemailStartedAt` (string)
    The date-time at which the voicemail left for this call started, or `null`
if there is no voicemail.

  - `data.channel` (string)
    The channel by which an interaction occurs—always `email` for `EmailInteraction`.
    Enum: "email"

  - `data.emailInReplyTo` (string)
    The contents of the `In-Reply-To` header, the unique [RFC5322
email message
ID](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4)
associated with the email being replied to. `null` if the header
wasn't present in the email.

  - `data.emailMessageId` (string)
    The contents of the `Message-ID` header, the unique [RFC5322
email message
ID](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4)
associated with this email. `null` if the header wasn't present
in the email.

  - `data.emailReferences` (string)
    The contents of the `References` header, a structured string of
[RFC5322 email message
IDs](https://www.ietf.org/rfc/rfc5322.html#section-3.6.4) that
identify the messages making up the email thread. `null` if the
header wasn't present in the email.

  - `data.channel` (string)
    The channel by which an interaction occurs—always `text` for `TextInteraction``.
    Enum: "text"

  - `data.twilioConvoSid` (string)
    The Twilio conversation SID associated with this interaction. (Only valid for interactions with a channel of text or chat)

  - `data.channel` (string)
    The channel by which an interaction occurs—always `chat` for `ChatInteraction`
    Enum: "chat"

  - `data.channel` (string)
    The channel by which an interaction occurs—always `mail` for `MailInteraction`
    Enum: "mail"

  - `data.mailIsCertified` (boolean)
    Whether or not this mail interaction is sent as [USPS Certified
Mail](https://faq.usps.com/s/article/Certified-Mail-The-Basics). Certified
mail provides proof of mailing and has more granular tracking
events, but incurs additional cost. Please refer to your order
form for more pricing information.
NOTE: Sending as certified mail is currently only supported for
the following subjects:
- `loanRightToCurePersonalUnsecured`
- `loanRightToCurePersonalUnsecuredColorado`
- `loanRightToCurePersonalUnsecuredDC`
- `loanRightToCurePersonalUnsecuredIowa`
- `loanRightToCurePersonalUnsecuredKansas`
- `loanRightToCurePersonalUnsecuredMaine`
- `loanRightToCurePersonalUnsecuredMissouri`
- `loanRightToCurePersonalUnsecuredSouthCarolina`
- `loanRightToCurePersonalUnsecuredWestVirginia`
- `loanRightToCurePersonalUnsecuredWisconsin`

  - `data.mailNumberOfPages` (integer)