|
2 | 2 | title: Ringing |
3 | 3 | description: How to ring the call and notify all members |
4 | 4 | --- |
| 5 | +The `Call` object provides several options to ring and notify users about a call. |
| 6 | +### Create and start a ringing call |
5 | 7 |
|
6 | | -## Ring & Notify |
7 | | - |
8 | | -You can ring or notify a call. Ring triggers an incoming call style UI for all members of the call. |
9 | | -Notify is a smaller notification. Commonly used when someone starts a livestream, joins a zoom style call etc. |
| 8 | +To create a ring call, we need to set the `ring` flag to `true` and provide the list of members we want to call. It is important to note that the caller should also be included in the list of members. |
| 9 | +For this, you can use the `create` method from the `Call` object. |
| 10 | +```kotlin |
| 11 | +val call = client.call("default", "123") |
| 12 | +call.create(ring = true, members = listOf("caller-id", "receiver-1", "receiver-2")) |
| 13 | +``` |
| 14 | +When ring is `true`, a push notification will be sent to the members, provided you have the required setup for push notifications. |
| 15 | +For more details around push notifications, please check [this page](./02-push-notifications/01-overview.mdx). |
| 16 | +If ring is `false`, no push notification will be sent. |
10 | 17 |
|
| 18 | +### Ring an existing call |
| 19 | +If you are sure that a call exists, you can use the `get` method instead: |
11 | 20 | ```kotlin |
12 | 21 | val call = client.call("default", "123") |
13 | | -call.create() |
| 22 | +call.get() |
14 | 23 | call.ring() |
15 | | -call.notify() |
16 | | - |
17 | | -// you can also ring and notify as a side effect of joining or creating a call |
18 | | -call.create(ring=true, notify=false) |
19 | | -call.join(ring=true, notify=false) |
20 | 24 | ``` |
| 25 | +The `get()` - `ring()` combination is better used for when calls are created and managed externally via another system. |
21 | 26 |
|
22 | | -Users who receive the incoming call can either accept or reject it. |
23 | | - |
| 27 | +### Monitor the outgoing call state |
| 28 | +The state of the ringing call is available via the `StreamVideo` client. |
24 | 29 | ```kotlin |
25 | | -call.accept() |
26 | | -call.reject() |
| 30 | +val client = StreamVideo.instance() |
| 31 | +val ringingCall = client.state.ringingCall |
27 | 32 | ``` |
28 | | - |
29 | | -The state for ringing calls is available here: |
| 33 | +This will give you a `StateFlow` which can be monitored. |
| 34 | +```kotlin |
| 35 | +ringingCall.collectLatest { call -> |
| 36 | + // There is a ringing call |
| 37 | +} |
| 38 | +``` |
| 39 | +or simply just get a current value. |
| 40 | +```kotlin |
| 41 | +val call = ringingCall.value |
| 42 | +``` |
| 43 | +### Canceling an outgoing call |
| 44 | +To cancel an outgoing call you can simply `reject` the call from the caller side. |
| 45 | +The `reject()` method will notify the endpoint that the call is being rejected and corresponding |
| 46 | +events will be sent. In order to cleanup on the caller side, a call to `leave()` is required. |
| 47 | +These two usually go together, unless there is a specific reason to keep the channel open for further |
| 48 | +events. |
30 | 49 |
|
31 | 50 | ```kotlin |
32 | | -val incomingCall = client.state.incomingCall.value |
33 | | -val accepted = call.state.acceptedBy.value // list of user ids who accepted |
34 | | -val rejected = call.state.rejectedBy.value // list of user ids who rejected |
| 51 | +call.reject() |
| 52 | +call.leave() |
35 | 53 | ``` |
36 | 54 |
|
37 | | -### Push Setup |
| 55 | +### Handle an incoming call |
38 | 56 |
|
39 | | -3 types of push notifications are triggered: |
| 57 | +If you have setup [push notifications](./02-push-notifications/01-overview.mdx) properly a "member" |
| 58 | +will receive a push notification about an incoming call. |
40 | 59 |
|
41 | | -* call.ring |
42 | | -* call.notification |
43 | | -* call.live_started |
| 60 | +By default the SDK will show the push notification (with a call style) with an option to either |
| 61 | +accept or decline the call. |
| 62 | + |
| 63 | +When the user clicks on a push notification. There is an intent fired `ACTION_REJECT_CALL` or `ACTION_ACCEPT_CALL`. |
| 64 | +The |
44 | 65 |
|
45 | 66 | You can learn more about how to setup [push notifications in the docs](./02-push-notifications/01-overview.mdx). |
46 | 67 | The docs also explain how to customize the notifications. |
47 | 68 |
|
48 | | -### Incoming Calls |
| 69 | +### Accept an incoming call |
| 70 | + |
| 71 | +The compose SDK provides built-in components to render and handle an incoming call. |
49 | 72 |
|
50 | | -The compose SDK provides built-in components to render an incoming call. |
| 73 | +One of them is `StreamCallActivity`. This abstract activity handles everything that is needed for a call. |
| 74 | +Stream also provides a default compose implementation of this activity called `ComposeStreamCallActivity`. |
51 | 75 |
|
| 76 | +These components are already predefined and registered in the SDK. If you want to customize them you can easily extend them as any other activity in Android. |
| 77 | + |
| 78 | +For more details check: |
52 | 79 | * [UI Component docs for incoming calls](../04-ui-components/04-call/04-ringing-call.mdx) |
53 | | -* UI Cookbook how to build [your own incoming call UI](../05-ui-cookbook/05-incoming-and-outgoing-call.mdx) |
| 80 | +* UI Cookbook how to build [your own incoming call UI](../05-ui-cookbook/05-incoming-and-outgoing-call.mdx) |
| 81 | + |
| 82 | +The Stream SDK provides a way to accept a call within the code so if you are building a new UI, you can do this via the SDK API. |
| 83 | +```kotlin |
| 84 | +call.accept() |
| 85 | +call.join() |
| 86 | +``` |
| 87 | +The above calls are all you need to accept and join a call. |
| 88 | + |
| 89 | +Its important to note that if there is already an ongoing call you first have to leave that call. |
| 90 | +```kotlin |
| 91 | +val client = StreamVideo.instance() |
| 92 | +val activeCall = client.start.activeCall.value |
| 93 | +if (activeCall != null) { |
| 94 | + activeCall.leave() |
| 95 | +} |
| 96 | +``` |
| 97 | +All this needs to be done with a component that handles the accept action. |
| 98 | +```xml |
| 99 | +<action android:name="io.getstream.video.android.action.ACCEPT_CALL" /> |
| 100 | +``` |
| 101 | + |
| 102 | +### Reject an incoming call |
| 103 | + |
| 104 | +Clicking the notification will automatically reject the call. |
| 105 | +There are certain instances that you might want to do this manually in your code. |
| 106 | + |
| 107 | +Stream offers a simple API to do this. |
| 108 | +```kotlin |
| 109 | +call.reject() |
| 110 | +``` |
| 111 | + |
| 112 | +Note that rejecting the call will notify the caller and other members that the participant rejected |
| 113 | +the call. However it will not clean up the local `call` state. |
| 114 | +For this you need to leave the call by using: |
| 115 | +```kotlin |
| 116 | +call.leave() |
| 117 | +``` |
| 118 | + |
0 commit comments