Overview

Warning

GrapeCall is available under a special license. Please, contact our sales department to get one.

You can start a GrapeCall by clicking on video icon on a group or private message. If this is a group, all members on this group will see a message o join the call. You can also invite more people by just searching for then while in the call and they will receive the incoming call on their devices.

If this is a private conversation, that is, a 1:1 call, then as soon as you click on the video button, the other user will se the same incoming call as before.

Data Flow

The data flow diagram bellow describes how data flow between clients and backend:

GrapeCall Data Flow

Some RPCs were developed to enable this flow. You can see bellow examples used on web client:

grapeClient.rpc({
  ns: 'calls',
  action: 'call',
  args: [{"channel_id": 1}],
})

Please see RPC Namespaces & Methods for a complete list of RPCs and PubSub Events for all related events.

GrapeCall Life-Cycle

Some concepts are important to understand GrapeCall life-cycle:

Keep Alive

All clients connected to a GrapeCall must periodically send a “keep alive” to the server. This is done via a simple RPC call (see alive()). Sending a keep alive means user is still connected and, thus, not sending it means user had connectivity issues. In this case, a parallel process will clean all related data and make sure all sessions are properly ended. For more information about this process, please check Cleaner.

Every time a keep alive is sent, two values are updated: call last update time and member last update time.

Read more about how to configure keep alive period.

GrapeCall Lifespan

GrapeCall lifespan is the amount of time a call should be considered active after the last keep alive was sent. That is, if a call is not updated within this period and its status is still on going, the system will automatically finish it when the clean up process runs. That is, a GrapeCall is considered finished if:

now - last_update > grapecall lifespan

Read more about how to configure GrapeCall Lifespan.

Member Lifespan

This is similar to GrapeCall Lifespan but it’s related to a call member. GrapeCall keeps the last time a user sent a keep alive. A user will be considered not in call anymore if he doesn’t send a keep alive after the lifespan period passes, that is:

now - last_update > member lifespan

Read more about how to configure member Lifespan.

Breaking the cycle

In a perfect world, all “keep alive” requests are properly sent and the GrapeCall just flows. However, in the real world a user can loose connectivity to the server and miss one or more keep alive cycles. We need to somehow manage this and make sure his partner doesn’t keep talk alone or keep waiting for something that won’t happen. In order to have a better control of call flow, both GrapeCall object and call member objects have an attribute called last_update. As already said, this attribute is updated everytime a keep alive is received by the server. An outdated last_update has some impacts:

1:1 calls

In case the GrapeCall is over a private conversation channel, that is, a 1:1 call, a disconnectivity means the call should end as the partner is not there anymore. So, the clean up process will proper finish the call and make sure both users are “online” again and, thus, can be called again.

Group Calls

In this case, the clean up process won’t simply finish the call but will first check if there are other users still “alive”. If not, then the call will be finished. This process will also make sure that the status of the user who had the issue is put back to the one he had before, that is, he won’t be “in call” anymore and can join any call again (or be invited).

Configuring GrapeCall Properly

You may have notice that there are an intrinsic relation between GRAPE_CALL_KEEP_ALIVE_PERIOD_SEC, GRAPE_CALL_LIFESPAN_SEC and GRAPE_CALL_LIFESPAN_SEC values.

They should be chose wisely so as to no incur in issues with automatically disconnections and so. This will become clear with this example: suppose we have a group call starting at 14:00h (round time to make the example easier). Also, suppose we have the following values:

GRAPE_CALL_KEEP_ALIVE_PERIOD_SEC=10
GRAPE_CALL_LIFESPAN_SEC=30
GRAPE_CALL_MEMBER_LIFESPAN=20
GRAPE_CALL_CLEANER_SEC=35

So, at 14:00:10, the first keep alive will be sent. Then, at 14:00:10h the second one an so on. So, when the cleaner run at 14:00:35, everything will be fine.

Now, suppose that at 14:10:00, the user enters a tunnel or so and looses his connection and the keep alive is not sent. Then, 10s later at 14:10:10, the keep alive is not sent again. Same at 14:10:20 and 14:10:30, that is, a total disconnection time of 30s. So, when the cleaner runs, it will find out that user didn’t send the keep alive for 30s (remember that member lifespan is 20s) and will then remove the user from the call. This means the user will be “online” again in the organization. Moreover, the call itself was also not updated for 30s (remember that the user is alone there) and will also be finished.

Note

Notice that the cleaner runs every GRAPE_CALL_CLEANER_SEC (35s in this example). This doesn’t mean every 35s after a full minute (14:00:35, 14:01:35, 14:02:35 etc) but every 35 since the job was started. So, if you restart your server at 10:00:00am, ths job will run at 10:00:35, 10:01:10s and so on. In the above example, we said the job would run at 14:00:35 just for simplicity and clarity.

It should be clear by now the kind of issues a misconfiguration may have: for example, a call lifespan of 30s is incompatible with a keep alive period of 1 minute. Same way, a member lifespan greater than the call lifespan in senseless. Usually, it shouldn’t be necessary to change those values but if you need to change, make sure to choose proper values or contact Grape for support.