Skip to content
/
Send message

Send message

Request

Send a message and save it as a new interaction.

The message is checked against Compliance Guard and may be rejected if it violates any rules.

If the message is accepted, it is queued for send. You can check the status of the queued interaction by calling GET on /interactions/{interactionId} endpoint with the interaction ID returned by this endpoint.

Context Variables

Hydratable Context Variables

Certain context variables can be "hydrated" by this endpoint for use in the template being rendered for sending.

For instance, if you provide a loanId in the request body it is "hydrated" to a loan object and passed to the context. This means you can then reference things like {{loan.displayId}} when customizing the template.

  • companyId hydrates to company
  • loanId hydrates to loan
  • loanIds hydrates to loans
  • caseId hydrates to case

No Automatic Context Variables

Note that this endpoint does not automatically fill in context variables.

If the template you're sending requires context variables, you must provide them. This can sometimes be confusing because Peach will automatically calculate and include context variables when the system sends a message automatically. See System Sent Messages for more information.

Difference from /interactions endpoint

Note this is different from POSTing to a /interactions endpoint because those endpoints create the interaction object, but do NOT send an actual message. (You can think of that endpoint as creating a historical log of an interaction which happened elsewhere.)

Security
oauth2(Required scopes: communicator:send) or bearerAuth or apiKeyHeader
Bodyapplication/jsonrequired
attachmentsArray of strings

List of document IDs for documents to attach to the outgoing email.

caseIdstring

Mark a particular case as associated with this message.

Hydates to the case context variable for use in the template being rendered for send.

Example:"CS-AAAA-BBBB"
channelSendMessageChannel (string) or Array of strings
One of:

The channels the Send Message endpoint can deliver to. This is a subset of the full InteractionChannel enum: fax, chat, gui, and document are not valid send channels and requests using them are rejected with a 400.

string(SendMessageChannel)
Enum:"voice""email""text""mail"
contactIdstring

The Contact ID of the borrower to which this message should be sent.

If not provided then the system will try to select an appropriate contact based on the type of message being sent. (e.g., if this is an email select the primary email address; if this is a text message select the borrower's mobile phone.)

Example:"BO-AAAA-BBBB"
contextobject or autopayAmountChanged (object) or autopayCanceledBySystem (object) or autopayEnabled (object) or autopayEnableReminder (object) or autopayPaymentCanceled (object) or autopayPaymentMethodUpdated (object) or autopayPaymentReminder (object) or autopayPaymentRescheduled (object) or cardExpiresReminder (object) or ceaseCommunicationAcknowledgement (object) or ceaseCommunicationRefuseToPay (object) or confirmationCode (object) or contactTakeover (object) or customX (object) or debtValidationNotice (object) or debtValidationNoticeArizona (object) or debtValidationNoticeAutomatic (object) or debtValidationNoticeNYCYonkers (object) or debtValidationNoticePuertoRico (object) or deceasedConfirmationOfPayoff (object) or deceasedNoticeToRepresentative (object) or deceasedNotificationUponDeath (object) or disputeOfDebtSubmitDocumentation (object) or disputeOfDebtConfirmed (object) or disputeOfDebtSubmitDocumentationReminder (object) or disputeOfDebtUnableToConfirm (object) or disputeOfDebtUnableToResolve (object) or electronicConsentOptOut (object) or failedSettlementInvestor (object) or freeFormBranded (object) or futurepayCanceledf (object) or futurepayPaymentDueReminder (object) or identityTheftIncompleteDocumentation (object) or identityTheftSubmitDocumentationFirstReminder (object) or identityTheftSubmitDocumentation (object) or identityTheftSubmitDocumentationSecondReminder (object) or identityTheftValidated (object) or identityTheftNotValidated (object) or autopayAgreement (object) or drawFundsDisclosure (object)(ContextObject)
Any of:

The data used to render the template. Provided in JSON format, it must be a mapping of context variables to values.

The context variables of borrower, loan, case and statement do not need to be provided since the system will automatically add these objects to context assuming you provide personId, loanId, caseId and statementId to the endpoint.

For example if your provided the context...

{
  "dateSigned": "Aug 27, 2021"
  "lenderName": "Peachy Lender"
  "paymentMethod": "bankAccount"
  "paymentMethodLastFour": "1110"
  "supportEmail": "support@peach.com"
  "supportPhone": "888-888-8888"
}

...then a template like Hello from {{lenderName}}! would render like Hello from Peachy Lender!

object
interactionExternalIdstring, <= 50 characters

The external ID of the interaction that will be created as a result of this request. Subsequent attempts to send with the same external ID will be blocked.

isTransactionalboolean(SendIsTransactionalDefaultTrue)

If true, then sent this interaction as "transactional".

Transactional interactions are those which are sent via an automated system in response to an event or some action taken. e.g., an email sent to confirm a payment was made is transactional; likewise an email sent to confirm a password change is transacrtional. Examples of non-transactional messages would be: those sent by an agent in response to a customer request, for collections, or for marketing.

It's important to mark these messages correctly, because different laws may apply to messages depending on if they're considered "transactional".

Additionally, a transactional interaction may be sent with different "From:" and "Reply-To:" fields depending on configuration. The purpose here being that it may be desirable to send messages from an email address that is clearly marked as "unmonitored", so that recipients do not try to respond directly to those email addresses.

Default:true
loanIdstring(schemas-AssociatedLoanId)

The ID of a Loan. This marks a particular loan as associated with this interaction.

Hydrates to the loan context variable for use in the template

Example:"LN-AAAA-BBBB"
loanIdsArray of strings(schemas-AssociatedLoanIds)

The IDs of several loans. This marks several loans as associated with this interaction.

Hydrates to the loans context variable for use in the template

Example:
[
  "LN-AAAA-BBBB",
  "LB-CCCC-DDDD"
]
overrideRecipientstring or null, non-empty

The recipient to which this message should be sent. This should be used in special cases where you cannot create a Contact and use contactId.

WARNING: It is not recommended to use this field. Instead use contactId to specify the contact.

You can only use this field if:

  • The interaction channel is email
  • A borrowerId is specified
  • A previousInteractionId is specified, to an email interaction belonging to that borrower
  • That previous interaction was sent "from:" the same email address as the one you want to send to. Currently only email addresses are supported for this field.
overrideTemplateIdstring or null(OverrideTemplateId)

The template version ID (like TV-AAAA-BBBB) or template descriptor ID (like TD-AAAA-BBBB) to use.

If a template descriptor is given, then the current template descriptor's activeVersionId is used.

This should be used in special cases where you do not want to use the implicit template selected by the subject and channel fields.

Example:"TV-AAAA-BBBB"
personIdstringrequired

The Borrower ID of the borrower to which this message should be sent.

Hydates to the person context variable for use in the template being rendered for send.

Example:"BO-AAAA-BBBB"
previousInteractionIdstring
sendAtstring, (date-time)

This attribute determines when the message should be sent. If set to null, and the message's timing conflicts with Compliance Guard's time-of-day restrictions, Communicator will automatically reschedule it to an allowable time. If this auto-rescheduling occurs, the sendAt field in the Interaction response will show the new scheduled time, and the Interaction status will be marked as scheduled.

To bypass auto-rescheduling, input the current time for sendAt when calling the endpoint.

Additional Information:

  • Regardless of when the message is scheduled to send, its content will be generated immediately upon calling this endpoint.
  • You can manually set a future send time of up to 7 days in the future.
sendJitterinteger, (int32)

The maximum number of seconds to add to the send time for this communication. The actual time added will be between 0 and this value. This is useful for spreading out the delivery of a large batch of messages over a period of time in order to avoid delaying other time-sensitive communcations.

statementIdstring

Mark a particular statement as associated with this message.

Example:"SM-AAAA-BBBB"
strictUndefinedboolean

If true an error will be returned if the template contains a variable that is not defined in the context. For historical reasons this is false by default, but it is recommended to set this to true.

Default:false
subjectstring(InteractionSubject)required

The subject of the interaction. The subject identifies the category of the content in the message.

Most subjects have an associated implicit theme. e.g., loanOverdueFirstNotice has a theme of opsCollDebt. For these subjects it is not necessary to specify a theme.

Some subjects like freeForm and custom<N> do not have an implicit theme. When using these subjects you must specify a theme.

DEPRECATED: locStatementGenerated and locStatementRegenerated are deprecated. They will be automatically converted into statementGenerated and statementRegenerated respectively. You should switch to use those subjects directly.

DEPRECATED: failedSettlementPeach is deprecated. This was always a subject used by the Peach application internally, and will no longer be used. Attempts to set this subject will be rejected with a 400 error.

Enum:"annualPrivacyPolicyNotice""autopayAgreement""autopayAmountChanged""autopayCanceledBySystem""autopayEnabled""autopayEnableReminder""autopayPaymentCanceled""autopayPaymentMethodUpdated""autopayPaymentReminder""autopayPaymentRescheduled"
supercaseBulkOperationIdstring
themestring or null(InteractionTheme)

The reason why an interaction occurred.

For example:

  • An outbound debt collection call should be marked as opsCollDebt.
  • An annual privacy policy update email should be marked as opsServicing.
  • A customer service response to borrower's inquiry should be marked as opsServicing.

DEPRECATED: inbBug, inbHumanLove, and opsServicingNegativeCreditReportNotice are deprecated: you cannot create or update interactions to have these values.

Enum:"agentNotification""opsCollDebt""opsCollLocateBorrower""opsCollVerifyEmployment""opsCollContactEmployerNotice""opsServicingDebtValidation""opsServicingNegativeCreditReportNotice""opsServicingTimeBarredNotice""opsServicing""opsAccountCredentials"
useTemplateboolean

Only applicable when channel=mail. If false, will not generate content from a template and will instead only use the documents referenced in the attachments field.

Default:true
POST
/communicator/send
curl -i -X POST \
  https://sandboxapi.peach.finance/api/communicator/send \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "attachments": [
      "string"
    ],
    "caseId": "CS-AAAA-BBBB",
    "channel": "voice",
    "contactId": "BO-AAAA-BBBB",
    "context": {},
    "interactionExternalId": "string",
    "isTransactional": true,
    "loanId": "LN-AAAA-BBBB",
    "loanIds": [
      "LN-AAAA-BBBB",
      "LB-CCCC-DDDD"
    ],
    "overrideRecipient": "string",
    "overrideTemplateId": "TV-AAAA-BBBB",
    "personId": "BO-AAAA-BBBB",
    "previousInteractionId": "string",
    "sendAt": "2019-08-24T14:15:22Z",
    "sendJitter": 0,
    "statementId": "SM-AAAA-BBBB",
    "strictUndefined": false,
    "subject": "annualPrivacyPolicyNotice",
    "supercaseBulkOperationId": "string",
    "theme": "agentNotification",
    "useTemplate": true
  }'

Responses

OK

Response
No content