RPC Namespaces & Methods

calls

class grapecall.rpc.Calls(user, **kwargs)

Namespace for all relevant RPC methods related to GrapeCall.

You can find how to proper use them by checking the Data flow.

alive(params: dict)

Keeps a call alive. This RPC should be periodically called in order to keep the call alive. You must get this value from the server instead of defining your on. Please, check Define the ringing duration.

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call}

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

call(params: dict)

Creates a new Grape Call. If the channel used is a private conversation, calling this RPC will make the partner’s device to start ringing for some time (check Define the ringing duration). The call won’t start until the partner picks up the call.

If the channel is a group, then the call will start immediately but no on would be directly notified.

If there is already an ongoing call on that channel, user will be joined to that call.

Parameters

params (dict) –

a dictionary containing the channel_id:

{"channel_id": ID of the channel}

These events will be triggered:

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call InvalidOperation – If the partner is not reachable

cancel(params: dict)

Cancels a call. This RPC should be used when user cancels a call or when call is automatically canceled after ringing for some time ( check Define the ringing duration). If this is a 1:1 call, it will immediately finish the call.

Note

This RPC should not be used for Group Calls

These events will be triggered:

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call}

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

cancel_invitation(params: dict)

Cancels an invitation. This RPC should be used when user cancels an invitation sent to another user.

Parameters

params (dict) –

a dictionary containing the call ID:

{
  'call_id': ID of the call,
  'users': list of users IDs
  'manual': true if the cancel button was pressed or false if it was automatically canceled. Default is false
}

Returns

A JSON object with the following fields:

  • invited (list) - a list with the ID of all actually invited users

Return type

Object

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

get(params: dict)

Returns all information about a call

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call}

Returns

An Object with all relevant call data:

  • id (string): ID of the call

  • channel (int): ID of the channel

  • finished (string) - ISO8601 timestamp

  • initiator (int): ID of the user who initiated the call

  • last_update (string) - ISO8601 timestamp

  • members (list): list of IDs of the users in this call

  • invited_members (list): list of user objects:

    • id (int) - ID of the user

    • avatar (string) - an image to be displayed as user avatar

    • display_name (string) - a text to be displayed as user name

    • invited_by (id) - ID of user who sent the invitation

  • message_id (string): ID of the system message related to the call

  • started (string) - ISO8601 timestamp

  • state (string) - current call state

  • max_users_in_call (int) - max number of users in the call

Return type

Object

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

get_calls(params: dict)

Returns all calls a user joined for an organization

Parameters

params (dict) –

a dictionary containing the call ID:

{"organization_id": ID of the organization}

Returns

A list of Grape Call objects with all relevant call data:

  • id (string): ID of the call

  • channel (int): ID of the channel

  • finished (string) - ISO8601 timestamp

  • initiator (int): ID of the user who initiated the call

  • last_update (string) - ISO8601 timestamp

  • members (list): list of IDs of the users in this call

  • invited_members (list): list of user objects:

    • id (int) - ID of the user

    • avatar (string) - an image to be displayed as user avatar

    • display_name (string) - a text to be displayed as user name

    • invited_by (id) - ID of user who sent the invitation

  • message_id (string): ID of the system message related to the call

  • started (string) - ISO8601 timestamp

  • state (string) - current call state

  • max_users_in_call (int) - max number of users in the call

Return type

List

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access this RPC

Generates an invite_link for external users to join a Grapecall

Requires calling user to have grapecall.can_start permission for the given channel

Calling this endpoint creates a new GrapeCallInvite valid for 1 hour from “now” and return the absolute URL

:param params (dict) - must contain “channel_id” or “call_id” or “organization_id” if “organization_id” is provided, a long-living channel-independent invite link will be generated otherwise “channel_id” or “call_id” must be provided so it’s clear to which channel’s call an invite link should be generated

Returns (dict) - a JSON dict with one key/value pair

invite_link: <absolute URL to use the invite>

get_token(params: dict)

Get Jitsi authorization token

Parameters

params (dict) –

a dictionary containing the channel_id:

{"channel_id": ID of the channel}

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

hangup(params: dict)

Hung up a call. This RPC should be called after a user leaves a call. If this is a 1:1 call, it will immediately finish the call.

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call,

”session_key”: session key of a Grape Call Session}

These events will be triggered:

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

invite(params: dict)

Invites users to a call

Parameters

params (dict) –

a dictionary containing the call ID:

{
  'call_id': ID of the call,
  'users': list of users IDs
}

join(params: dict)

Joins a call. This RPC should be called when a user accepts an incoming call. It will also properly set user status to “in call”.

Parameters

params

a dictionary containing the call ID:

{"call_id": ID of the call}

These events will be triggered:

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

log(params: dict)

Collects Grape Call logs from agents. A agent can be mobile clients or server-side agents (e.g. an agent running on JITSI server.

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call,

”agent”: a string identifying the agent, “message”: the message to be logged}

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

reject(params: dict)

Rejects a call. This RPC should be called when the receiver rejects an incoming call notification. If this is a 1:1 call, it will immediately finish the call.

Parameters

params (dict) –

a dictionary containing the call ID:

{"call_id": ID of the call}

These events will be triggered:

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call

search_users(params: dict)

Search for a user within a channel, based on their username, email, and display name. Result is sorted by similarity if a search text is provided or by joined date, if there is no search text.

Parameters

params (Object) –

  • channel_id (int) - ID of a channel within which where the user should be looked up

  • search_text (string) - The text to search for

  • limit (int) - maximum of entries to return (defaults to 25)

  • after (string) - ISO8601 timestamp specifying where in the ordered list of room members to begin – the returned members will have a joined_at timestamp strictly grater than this value. Optional

Returns

A JSON object with the following fields:

  • total (int) - the total number of members

  • results (array[object]) - a list of objects representing the top matches with the following fields:

    • id (int)

    • username (string)

    • email (string)

    • avatar (string) - URL of the avatar

    • display_name (string)

    • status (int) - presence status within the organization:

      • null: status events disabled

      • 0: offline

      • 4: reachable

      • 8: in call

      • 16: online

  • next_page (object) - the value of params to use to get the next page of members; null if there cannot be a next page

Return type

Object

Raises

instant.rpc.UserExceptionNotAuthorized – If the requesting user has insufficient rights to access call