README

This library makes it easy to work with...

the Riddle API v3
incoming Riddle webhooks (validates & parses them)

Available endpoints can be found here.

Installation

To use this library you need to have PHP 7.4 or higher (8.0 / 8.1) installed.

With composer

When working with composer all you need to do is run the following command:

composer require riddle/client-sdk

In your .php file you can then include the composer autoloader:

require 'vendor/autoload.php';

// [... your code, e.g. fetching riddles / stats / ...]

Without composer

To use it without a package manager download this repository, extract it, keep the src/ folder and include the Client.php file in your project:

require 'riddle-client/src/Client.php';

$client = new Riddle\Api\Client('...');

Authentication

When using the API you need to authenticate yourself with an access token. You can create one in your Riddle account (you must be logged-in to view this page). You can then pass the token to the client:

require 'riddle-client/src/Client.php';

$client = new Riddle\Api\Client('access token');

Now you're ready to use the API.

Example usages

Get all riddles

require 'riddle-client/src/Client.php';
require 'riddle-client/src/Service/Riddle.php';

$client = new Riddle\Api\Client('access token');
$riddles = $client->riddle()->list();

Get alltime stats for a Riddle (only available for Business & Enterprise plans)

require 'riddle-client/src/Client.php';
require 'riddle-client/src/Service/Stats.php';

$client = new Riddle\Api\Client('access token');
$riddleStats = $client->stats()->fetchRiddleStats('[RIDDLE_ID]');

Get riddles from team with tags

require 'riddle-client/src/Client.php';
require 'riddle-client/src/Service/Riddle.php';

$teamId = 123;
$tagIds = [2]; // to get tag IDs use the tag list endpoint
$client = new Riddle\Api\Client('access token');
$riddles = $client->riddle()->list($teamId, null, $tagIds);

Parse webhook

require 'riddle-client/src/Webhook/Webhook.php';

try {
    $webhook = new Riddle\Api\Webhook\Webhook('WveoGBv11xet392jUwPWbmEbicUn13zR');
    $payload = $webhook->parse();
    \file_put_contents(__DIR__.'/test-webhook.json', \json_encode($payload->getPayload())); // log the webhook payload

    // now work with the payload
    $resultId = $webhookResponse->getResultData()['blockId'];
    // ...
} catch (\Throwable $ex) {
    \file_put_contents(__DIR__.'/exception.txt', $ex->getMessage()); // write to a log file in case of an exception
}

Note: The webhook signature key is not required - if it's not given the signature validation will be skipped.

Build riddles

You can also build riddles via the API.Please note that this feature is currently in-beta and is expected to be expanded in the future.

Please drop us any feedback you have on this feature via support chat on riddle.com or send us an email @ hello@riddle.com!

To use this feature, create an instance of either PollBuilder or QuizBuilder:

require 'riddle-client/src/Client.php';
require 'riddle-client/src/Builder/PollBuilder.php';

$client = new Riddle\Api\Client('access token');
$pollBuilder = new Riddle\Api\Builder\PollBuilder($client);

Build a poll

When building a poll you can:

set the title
add single choice questions
add multiple choice questions
set the single result the user will see at the end of the Riddle

Here's the full code snippet:

require 'riddle-client/src/Client.php';
require 'riddle-client/src/Builder/PollBuilder.php';

$client = new Riddle\Api\Client('access token');
$pollBuilder = new Riddle\Api\Builder\PollBuilder($client);

// configure the poll's settings, such as questions / title / result
$pollBuilder
    ->setTitle('My Riddle Title')
    ->addSingleChoiceQuestion('What is the answer?', ['Yes', 'No', 'Maybe'])
    ->addMultipleChoiceQuestion('What are the answers?', ['Yes', 'No', 'Maybe'])
    ->setResult('Thanks for participating!', 'We will process your answers accordingly.');

// requests the API and returns the built poll
$builtPoll = $pollBuilder->build();

Build a quiz

When building a quiz you can:

set the title
add single choice questions
add multiple choice questions
add as many results as you want, each with a title, description and score range (min/max)