Communicator

The channel by which an interaction occurs.

The content and attributes of the message sent. Normally in JSON format.

An identifier of an existing contact.

An identifier of a loan to track interactions for. This can either be Peach's or a lender's external identifier.

A list of identifiers of loans to track interactions for. This can either be Peach's or a lender's external identifiers.

The subject of the interaction. This is relevant only if the interaction was rendered from a Peach template.

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.
• Statements or payment reminders should be marked as outOpsLoan.

Set this flag if this interaction has sensitive information. The flag is used for proper authorization of access to the information.

The lender's identifier for the interaction.

After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

If a previous interaction identifier is provided, the current and previous interactions will be linked. This can either be Peach's or a lender's external identifier.

The status of an interaction.

status is important, as it can impact future interactions. For instance, in jurisdictions which cap the number of outbound collection communications to a borrower, status=failed interactions do not count against the legal allotment.

Interaction status can be updated as the interaction status changes. For example, when an email is sent, set the status to attempted. If the email is opened, set the status to succeeded. If the email bounces, set the status to failed. attempted is assumed to be a successful interaction. Optionally, you can also use 'statusDetails' to provide additional details about status.

In-Progress interactions

Some interactions—like an email—take place at a single point in time, others might be ongoing for many minutes—like a phone call.

Ongoing interactions like voice and chat may have their status set to inProgress.

Scheduled interactions

Some interactions might be scheduled for the future. These interactions have a status of scheduled. If this scheduled interaction is unscheduled then it has a status of canceled.

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Store any type of key/value pairs in the form of a JSON dictionary.

true when this interaction is considered "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 because a payment has been made is transactional. An example of a non-transactional message is a one sent by an agent in response to a customer request or for collections.

Note: Can be null for interactions sent before the transactional-ness was added to the API.

The lender's identifier of the contact information.

This should not include any ext- prefix as we know this is an external ID field.

Provides details on the outcome of the interaction according to an agent.

Note this captures the "human" outcome of an interaction: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

For the "technical" status of an interaction, see statusDetails. e.g., : Did it fail to send? Was it blocked by Compliance Guard?

• voiceSpokeWithFirstParty - Agent spoke with borrower
• voiceSpokeWithThirdParty - Agent spoke with someone other than the borrower
• voiceLeftVoicemail - Agent left voicemail
• voiceReachedVoicemailNoMessageLeft - Agent reached voicemail but did not leave a message
• voiceRangNoPickup - Phone rang, no voicemail was reached, and the call ended, or the agent hung up
• voiceLineBusyNoRing - Agent reached busy phone line
• voicePickedHungUp - Agent heard call pick up and immediate hang up
• voiceDisconnectedWhileQueuedOnHold - Caller hung up while on hold
• voiceUnexpectedDisconnect - The call was unexpectedly disconnected
• voiceFailedToInitiate - Outbound voice call could not start for some reason
• voiceNumberDisconnected - Outbound voice call to disconnected phone number

Provides more details about the status of an interaction.

Note that statusDetails related to the "technical" status of an interaction: e.g., Did it connect? Did it fail to send? Was it blocked by Compliance Guard?

For the "human" outcome of an interaction see agentOutcome: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

Status

Certain status details must have a particular status associated with them; attempting to use them otherwise will result in an error.

Succeeded

The following status details are considered status=succeeded

• emailDelivered - The email was successfully delivered
• emailOpened - The email was opened
• chatRead - The chat message was read

Attempted

The following status details are considered status=attempted.

• voiceReceivedOutsideOpenHours - Caller tried to contact the lender outside designated business hours
• voiceConnected - Voice call connected successfully
• emailSent - Email was sent, but delivery cannot be confirmed
• mailSent - Mail sent
• chatPosted - Chat message sent
• textConvoTimeoutAutoclose - This text conversation was closed automatically due to a timeout.
• textConvoClosedStale - (Deprecated) An open but outdated text conversation was closed automatically when a new text conversation was started. New text conversations should never enter into this state, but old conversations may be in this state.
• textConvoClosedByAgent - The agent manually marked the text conversation as ended.

Failed

The following status details are considered status=failed.

Generally an interaction is failed if some part of connecting or completing the interaction failed due to a technical failure, misconfiguration, or attempt to communicate in a way disallowed by rules.

• voiceFailedToInitiate - Outbound voice call could not start for some reason
• voiceNumberDisconnected - Outbound voice call to disconnected phone number
• voiceLenderDisabledInboundCalls - Inbound call received while lender has inbound voice call disabled
• voiceReceivedNoAgentsAvailable - Inbound call received while lender had no agents to answer it
• emailBlocked - Receiving server could not or would not accept the message temporarily
• emailBounced - Receiving server could not or would not accept mail to this recipient permanently
• emailDropped - Email rejected for a number of reasons: rejected as SPAM, Unsubscribed Address, Bounced Address, Email Invalid
• emailFailedToSend - Not currently in use - reserved for future use
• emailReportedAsSpam - Email was delivered, but later reported as SPAM by recipient
• textLenderDisabledInboundTexts - The inbound text was not received because the lender does not have inbound texting enabled.
• textConvoUnknownNumberRejected - This text was received from an unknown number, and so was rejected.
• textQueueOverflow - Too many messages were queued to be sent, and some were dropped as a result.
• textAccountSuspended - The account was suspended between message queuing and delivery.
• textDeviceUnreachable - The destination phone number temporarily could not be reached - it was turned off, out of service area, etc.
• textMessageBlocked - The destination phone number is blocked from receiving the message.
• textNumberDisconnected - The destination phone number could not be reached and may be disconnected.
• textLandlineOrUnreachableCarrier - The destination phone number could not receive the message. Reasons include the destination number being a landline phone or the carrier being temporarily unavailable.
• textCarrierViolation - The message was flagged as 'objectionable' or 'spam' by the phone carrier and was blocked. See https://support.twilio.com/hc/en-us/articles/223181848-How-Does-Message-Filtering-Work-
• textUnknownError - An unknown error occurred when attempting to send the message.
• textMissingSegment - One or more parts of a multipart message were not received.
• textMessagePriceExceedsMax - The price of the message exceeds the max price parameter.

Channels

• Most status details can only be used with their respective channels. e.g., voiceNumberDisconnected can only be used for interactions with channel=voice. Using them otherwise will result in an error
• invalidContact and blockedByComplianceGuard are valid for all channels

Direction

Certain status details are only valid with certain direction settings. Using them with an invalid direction will result in an error. For example...

• voiceReceivedNoAgentsAvailable can only be set for inbound phone calls
• voiceNumberDisconnected can only be set for outbound phone calls
• voiceUnexpectedDisconnect can be set for either direction

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Start time of the interaction. If not provided we'll assume it's a timestamp of the API call. If time of day is not required provide only date.

For CRM-managed voice interactions, an inbound call is considered started when the CRM system answers the call, and an outbound call is considered started when the CRM system initiates the call.

End time of the interaction. This attribute is optional and is used for logging only.

For CRM-managed voice interactions, a call is considered ended when either the borrower or the agent disconnects.

Time to start the scheduled interaction.

Time to end the scheduled interaction.

Short text describing the failure reason. Normally displayed in UI.

Detailed text describing the failure reason and any appropriate actions the user may take to fix the issue.

The Compliance Guard rule identifier that blocked the interaction. Only applicable if the statusDetails=blockedByComplianceGuard and a rule actually blocked the interaction. In some cases the interaction can be blocked before rules are checked (e.g. a borrower is missing an address). In such a case the complianceGuardRuleId will be empty/null.

Represents various users such as a borrower, co-borrower, co-signer, etc. A lender can choose to provide PII or not. If no PII is provided, Peach cannot monitor for bankruptcy, deceased and SCRA.

The contact details. A contact can be email, phone, address, etc. The name attribute is optional, and is useful for third-party contacts such as spouse, attorney, etc.