Developer ForumDeveloper BlogAtlas
API Reference

Create a Text Message

post https://api.flow.ai/rest/v1/messages/

Send a text message with the Flow REST API.

Details

POST rest/v1/messages/EXAMPLE-853a-448f-9f91-ef397588ff87 HTTP/1.1
Host: api.flow.ai
Content-Type: application/json
Authorization: MY_MESSAGING_API_KEY
{
  "payload": {
    "type": "text",
    "speech": "hello",
    "originator": {
      "name": "John Doe",
      "role": "external",
      "profile": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "gender": "M",
        "locale": "en-US",
        "timezone": -5,
        "country": "us",
        "email": "[email protected]",
        "picture": "https://..."
      }  
    },
    "metadata": {
      "language": "en",
      "timezone": 5,
      "params": {
        "product": [{
          "value": "Dish washer"
        }],
        "problems": [{
          "value": "Noise"
        }, {
          "value": "Leaks"
        }]
      }
    }
  }
}

Originator

With each message, you need to provide some information regarding the sender, user or as we call it, the originator of the message.

Each originator has a role within the conversation. When sending messages to the REST API this can be either external or moderator.

The external role is used to indicate the originator is a customer, end-user, or external user sending a message. The moderator role is reserved for human agents or employees replying to customers or external users.

Specifying the right role is important. When Flow receives a message originating from a moderator, the bot will automatically pause.

Sync mode

The Flow REST API is asynchronous. Whenever a request is sent, a result will be returned to the configured webhook endpoint. There are circumstances that won't allow the use of a webhook endpoint to receive results.

For these use cases, we provide a synchronous mode for certain endpoints. Instead of returning the result of the API request to your webhook, it's returned directly as a response to the request.

📘

Sync mode is an exception and has several limitations for the messaging endpoint. For example, timers and delays cannot work in this mode! If you are considering using the Flow REST API to connect Flow to a client-side app, consider using the Flow Socket API first.

WriteConcern mode

Because of the asynchronous nature of the REST API, any call made to the endpoint will not guarantee that the system has completed the action when you receive a response.

For example, calling the resolve endpoint will immediately return a response to your request, but actually resolving the conversation might be done at a later time.

Using the writeConcern mode we guarantee the action has completed when you receive the response.

Language