carandclassic / talkjs
PHP client for TalkJS API
Installs: 47 811
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 0
Forks: 6
Open Issues: 2
Requires
- php: >=7.4
- ext-json: *
- symfony/http-client: ^4.4|^5.2|^6.0
Requires (Dev)
- phpunit/phpunit: ^9.5.4
This package is auto-updated.
Last update: 2024-10-23 10:04:48 UTC
README
Forked from shapintv/talkjs.
For more information on parameters, custom data, and other things you can send with this API, please see the TalkJS REST API documentation.
The structure of this package is crafted around the TalkJS REST API structure, and as such all the following are treated as distinct APIs:
- Users
- Conversations
- Messages
Not implemented currently:
- Notifications
- Sending file Messages
Install
Via Composer
$ composer require carandclassic/talkjs
Usage
This can be used as-is or with auto discovery in Laravel.
Create a TalkJSClient
use CarAndClassic\TalkJS\TalkJSClient; $appId = 'my_app_id'; $secretKey = 'my_secret_key'; $talkJSClient = new TalkJSClient($appId, $secretKey);
Laravel
Firstly, add TALKJS_APP_ID
and TALKJS_SECRET_KEY
to your env file. These are pulled in from the package's config automatically talkjs.app_id
and talkjs.secret_key
respectively.
If you'd like to change this, you can publish the application config and modify the talkjs.php
config file in your application:
php artisan vendor:publish --provider=CarAndClassic\\TalkJS\\Providers\\TalkJSServiceProvider
Laravel's automatic service discovery will let you dependency inject TalkJSClient
as per normal. Alternatively for one-off use you can also pass overriding appId
and secretKey
arguments using app()->make()
:
$talkJSClient = app()->make(TalkJSClient::class, ['appId' => 'my_custom_app_id', 'secretKey' => 'my_custom_secret_key']);
Input vs API data
Below you'll see "input data" and "API data" referenced.
- Input data = data you sent via this package
- API data = data returned from the API
This is done because currently TalkJS returns empty 200 responses for successful resource update/creation, but it's still helpful to return what you've sent along.
IDs
TalkJS IDs for users and conversations are custom and managed by your application.
Filtering
All endpoints that fetch multiple records (users, conversations, messages) have limit & pagination options. API usage below will use a $filters
variable where possible for demonstration, and it will look like this:
$filters = [ 'limit' => 50, 'startingAfter' => 'latestMessageId' ];
Creating a TalkJSClient
$appId = 'YOUR_APP_ID'; $secretKey = 'YOUR_SECRET_KEY'; $talkJSClient = new TalkJSClient($appId, $secretKey);
Users
Please note TalkJS currently does not offer a user deletion API, and instead recommend you use the update/edit endpoints to anonymise personally identifiable information.
- Creating or updating a user, returns
UserCreated
class with input data
$talkJSClient->users->createOrUpdate('my_custom_id', [ "name" => "Alice", "email" => ["alice@example.com"], "welcomeMessage" => "Welcome!", "photoUrl" => "https =>//demo.talkjs.com/img/alice.jpg", "role" => "buyer", "phone" => ["+1123456789"], "custom" => [ "foo" => "bar" ] ]);
- Retrieve a user, returns a
User
model class with API data
$talkJSClient->users->find('my_user_id');
- Get all users, returns an array of
User
model class with API data
$talkJSClient->users->find($filters);
- Get user's conversations, returns an array of
Conversation
model class with API data
$talkJSClient->users->getConversations('my_user_id');
Conversations
- Create or update a conversation, returns a ConversationCreatedOrUpdated event class with input data
$talkJSClient->conversations->createOrUpdate('my_conversation_id', [ 'subject' => 'My new conversation', 'participants' => ['my_user_id_1', 'my_user_id_2'], 'welcomeMessages' => ['Welcome!'], 'custom' => ['test' => 'test'], 'photoUrl' => null ]);
- Retrive a conversation, returns a Conversation model class with API data
$talkJSClient->conversations->get('my_conversation_id');
- Find conversations, returns an array of
Conversation
model class with API data
$talkJSClient->conversations->find();
- Join a conversation, returns a
ConversationJoined
event class with input data
$talkJSClient->conversations->join('my_conversation_id', 'my_user_id');
- Leave a conversation, returns a
ConversationLeft
event class with input data
$talkJSClient->conversations->leave('my_conversation_id', 'my_user_id');
- Delete a conversation, returns a
ConversationLeft
event class with input data
$talkJSClient->conversations->delete('my_conversation_id');
- Update participation settings (notifications and read/write access)
$notify = true; // Boolean, default true $access = 'ReadWrite'; // ReadWrite or Read, default ReadWrite $talkJSClient->conversations->updateParticipation('my_conversation_id', 'my_user_id', $notify, $access);
Messages
For more information on custom data and filters, please refer to the TalkJS documentation linked above.
Please note:
- Sending file attachment is not yet implemented.
- Endpoints that return multiple messages will return them in descending order, i.e. latest first.
$custom = [ 'foo' => 'bar' ];
- Get messages in a conversation, returns an array of
Message
model class with API data
$talkJSClient->messages->get('my_conversation_id', $filters);
- Find specific message in a conversation
$talkJSClient->messages->find('my_conversation_id', 'message_id');
- Post a system message, returns a
MessageCreated
event class with input data andtype
ofSystemMessage
$talkJSClient->messages->postSystemMessage('my_conversation_id', $text, $custom);
- Post a user message, returns a
MessageCreated
event class with input data andtype
ofUserMessage
$talkJSClient->messages->postUserMessage('my_conversation_id', $username, $text, $custom);
- Edit a message, returns a
MessageEdited
event class with input data
$talkJSClient->messages->edit('my_conversation_id', 'message_id', $text, $custom);
- Delete a message, returns a
MessageDeleted
event class with no data
$talkJSClient->messages->delete('my_conversation_id', 'message_id');
License
The MIT License (MIT). Please see License File for more information.