Receive and send messages

You can use the Bot Connector API to connect your bot to multiple channels, such as Messenger, Slack or Kik.

Once you've connected your bot to channels on the platform, you can use this SDK to receive and send messages.

Usage

Start by instantiating either a Client or a Connect object, as shown below:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Sapcai\Client;

$client = new Client('YOUR_TOKEN');
$request = $client->connect

// ...is the same as...

$request = Client::Connect('YOUR_TOKEN');

Connect

You can now connect your bot, access all incoming messages and send replies accordingly.

You can find more details on the message format your bot can send here.

Use SlimFramework

<?php
use Sapcai\Client;

// Start Slim server
$app = new \Slim\App();

// Instantiate the Connect Client
$connect = Client::Connect($_ENV["REQUEST_TOKEN"], $_ENV["LANGUAGE"]);

//Handle / route
$app->post('/', function ($request, $response) {
  $connect->handleMessage($body, 'replyMessage');
});

function replyMessage ($message) {
  // Get the content of the message
  $text = $message->content;

  // Get the type of the message (text, picture,...)
  $type = $message->type;

  $message->addReply([(object)['type' => 'text', 'content' => 'Hello, world']]);

  $message->reply();
}

// Run Slim server
$app->run();

Connect with SAP Conversational AI

This is a small example using both the Connect and the Request APIs to receive messages from a channel, send the content to SAP Conversational AI to get back the bot reply, and send it back to the channel.

<?php
use Sapcai\Client;

// Start Slim server
$app = new \Slim\App();

// Instantiate the SAP Conversational AI Client
$client = new Client($_ENV["REQUEST_TOKEN"], $_ENV["LANGUAGE"]);

//Handle / route
$app->post('/', function ($request, $response) {
  $client->connect->handleMessage($body, 'replyMessage');
});

function replyMessage ($message) {
  // Get the content of the message
  $text = $message->content;

  // Get the type of the message (text, picture,...)
  $type = $message->type;

  // Get the senderId, which we'll use as a conversation token.
  $conversationToken = $message->senderId;

  // If it's a text message...
  if ($type == 'text') {
    // ...make a request to SAP Conversational AI to get the bot reply...
    $response = $client->request->converseText($text, [ 'conversation_token' => $conversationToken ]);

    // ...extract the reply...
    $reply = $response->reply();

    // ...and send it back to the channel
    $message->addReply([(object)['type' => 'text', 'content' => $reply]]);
    $message->reply();
  }
}

// Run Slim server
$app->run();

Methods

Send messages to a specific conversation

Method	Params	Return
sendMessage($messages, $conversationId)	messages: Array[object], conversationId: String	object: the API response

This methods allow you to push a message to a specific conversation.

<?php
$messages = (object)[
  (object)[
    type: 'text',
    content: 'Roger that',
  ]
];

$connect->sendMessage($messages, 'A_CONVERSATION_ID');

echo 'Message successfully sent';

Broadcast messages to all bot conversations

Method	Params	Return
broadcastMessage($messages)	messages: Array[object]	object: the API response

This method allow you to push a message to all the conversations of your bot.

<?php
$connect->broadcastMessage($messages);

echo 'Message successfully sent';

Message

A Message object is what you receive in the Connect#handleMessage callback.

Attributes

An instance of the Message class provides each of the following attributes:

Attributes	Type
content	String: the content of the message
type	String: the type of the message
conversationId	String: the id of the conversation this message belongs to
token	String: the SAP Conversational AI token of the bot
chatId	String: the native ID of the chat
senderId	String: the native ID of the message's sender
attachment	Object: the raw content of the message

Methods

Add a reply to the message's array of replies

Method	Params	Return
addReply(messages)	messages: Array[object]	nothing

<?php
use Sapcai\Client;

// Start Slim server
$app = new \Slim\App();

// Instantiate the SAP Conversational AI Client
$client = new Client($_ENV["REQUEST_TOKEN"], $_ENV["LANGUAGE"]);

//Handle / route
$app->post('/', function ($request, $response) {
  $client->connect->handleMessage($body, 'replyMessage');
});

function replyMessage ($message) {
  $payload = [
    (object)[
      'type' => 'text',
      'content' => 'Hello'
    ],
    (object)[
      'type' => 'picture',
      'content' => 'MY_URL_IMAGE'
    ]
  ];

  $message->addReply($payload);
  $message->reply();
}

// Run Slim server
$app->run();

Send replies from the message

Method	Params	Return
reply(messages)	messages: Array[object]

<?php
use Sapcai\Client;

// Start Slim server
$app = new \Slim\App();

// Instantiate the SAP Conversational AI Client
$client = new Client($_ENV["REQUEST_TOKEN"], $_ENV["LANGUAGE"]);

//Handle / route
$app->post('/', function ($request, $response) {
  $client->connect->handleMessage($body, 'replyMessage');
});

function replyMessage ($message) {
  $payload = [
    (object)[
      'type' => 'text',
      'content' => 'Hello'
    ],
    (object)[
      'type' => 'picture',
      'content' => 'MY_URL_IMAGE'
    ]
  ];

  $message->addReply($payload);
  $message->reply();

  //...is the same as...

  $message->reply($payload)
}

// Run Slim server
$app->run();