# Rake Direct Use Case Scenarios

## Send Transactional, Reminder, or Marketing Messages

With the use of Rake Direct API you can inform and engage with your clients by sending SMS or Facebook Messenger messages directly to them.

Below is a popular example of a Rake Direct API request to send a SMS message about scheduling a package pickup. In this case, the only data known is a phone number.

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "secret":"Raqqw2k6bngAOmSk",
  "message":"Hello, your shipment of widgets has arrived. Please reply to this text or click on this link to schedule a pickup time.  https://mycompany.com/pickup ",
  "messageType":"text",
  platformIds: [1],
  "secondaryEntity":{
    "phoneNumber": "123456789012"
  },
  "session" : { "timeout": 1 }
}

> **NOTE:** For transactional messages, it is suggested that the session expires immediately (e.g. 1 second). After sending the message, if the customer sends a reply it starts a new session in Rake and that session routes natively into your Rake workspace to any available agent.

## System Event Notifications

Keep your team up to date about important notifications. You can use the Rake Direct API to send a message into an existing channel, group chat, or DM session in your Rake workspace.

For example, you can send your **#sales-team** channel (e.g. sessionId = 123) a message: "Great news! We just added a new tier 3 account, ABC Trucking Company."

In this case you will need to send the following request:

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "sessionId": 123,
  "secret": "Raqqw2k6bngAOmSk",
  "message": "Great news! We just added a new tier 3 account, {{CRMSystem.AccountName}}.",
  "messageType":"text",
  "initiatingEntity"?:{
    "entityId": 21,
    "email":"[e-mail]",
    "lastName":"Company Bot",
    "firstName": "CRM Notification"
  },
}

Note: the message will be sent from the the entity described in the initiatingEntity field. If that field is blank, the message will be sent on behalf of workspace.

Attention: Value of the secret is unique for every workspace and can be generated during Rake Direct configuration.

## Create a session with a 3rd Party chat system

If your CRM or any other external system supports chats or instant messaging, you can use our Rake Direct API to create a session and then manage it from the 3rd Party system.

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "secret":"<secret>",
  "returnWebhookUrl":"<webhookUrl>",
  "returnWebhookSecret": "<webhookSecret>",
  "custom": "<customField>",
  "message":"text message",
  "messageType":"text",
  "platformIds":[number],
  "initiatingEntity":{
    "email":"<email>",
    "lastName":"<last name>",
    "firstName": "<first name>"
  },
  "secondaryEntity":{
    "entityId": "<entityId>"
  },
  "session" : { "timeout": 3600 }
}

You will receive a sessionId in responce to this API request. Messages for a client will be routed to returnWebhookUrl. To send the answer to the client, use the following API request:

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "sessionId": number,
  "secret":"<secret>",
  "message":"<text message>",
  "messageType":"text",
  "initiatingEntity"?:{
    "entityId": number,
    "email":"<email>",
    "lastName":"<last name>",
    "firstName": "<first name>"
  },
}

## Add your custom widget to the Rake system

You can create an HTTP connection (between your widget and Rake) with the Rake system and send messages that will be processed as regular messages.

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "secret":"<secret>",
  "returnWebhookUrl":"<webhookUrl>",
  "returnWebhookSecret": "<webhookSecret>",
  "custom": "<customField>",
  "message":"text message",
  "messageType":"text",
  "initiatingEntity":{
    "email":"<email>",
    "lastName":"<last name>",
    "firstName": "<first name>"
  },
  "session" : { "timeout": 3600 }
}

You will receive a sessionId in responce to this API request. Messages for a client will be routed to returnWebhookUrl. To send the answer to the client, use the following API request:

curl -X POST https://rakesystem.rake.ai/workspaces/:workspaceId/rake-direct -d \
{
  "sessionId": number,
  "secret":"<secret>",
  "message":"<text message>",
  "messageType":"text",
  "initiatingEntity"?:{
    "entityId": number,
    "email":"<email>",
    "lastName":"<last name>",
    "firstName": "<first name>"
  },
}