Send Message - IoT SDK

The Data Channel lets your device exchange messages with the other participants in the meeting, alongside its audio and video. Use it to send control commands, sensor readings, or status updates between the device and everyone else in the call.

Sending a message is a two-step flow: open the message channel once with startMessageChannel(), then call sendMessage() as often as you need.

note

The message channel works on all supported boards.

startMessageChannel()

• The startMessageChannel() function opens the data channel used for application messages. Call this once after init() and before your first sendMessage(). It is idempotent, so calling it again has no effect.
• This function takes no parameters.

note

You must call the init() method before invoking startMessageChannel(). If not, the function returns an INIT_NOT_CALLED result code.

Example

#include "videosdk.h"
#include "esp_log.h"
void app_main(){
  result_t r = startMessageChannel();
  if (r != RESULT_OK)
    ESP_LOGE("IOT-SDK", "startMessageChannel failed: %d", r);
}

sendMessage()

• The sendMessage() function sends a single application message to the other participants in the meeting.

This function takes three parameters:

• data: pointer to the message bytes. The data is copied internally, so you may reuse or free your buffer immediately after the call returns.
• len: length of the message in bytes. The maximum message length is 24000 bytes.
• is_binary: pass 1 to send a WebRTC binary message, or 0 to send a UTF-8 text message.

caution

• Call startMessageChannel() before sending. If you call sendMessage() first, it returns a DATA_CHANNEL_NOT_STARTED result code.
• If the send queue is momentarily full, sendMessage() returns DATA_CHANNEL_QUEUE_FULL; retry shortly.
• Passing a NULL buffer, a length of 0, or a length greater than 24000 returns NULL_PARAMETER.

Example

#include "videosdk.h"
#include "esp_log.h"
#include <string.h>

// Send a UTF-8 text message.
void send_text_message(const char *text){
  result_t r = sendMessage((const uint8_t *)text, strlen(text), /*is_binary=*/0);
  if (r == RESULT_OK)
    ESP_LOGI("IOT-SDK", "msg sent (text): %s", text);
  else
    ESP_LOGW("IOT-SDK", "msg send failed: %d", r);
}

// Send a raw binary message.
void send_binary_message(const uint8_t *data, size_t len){
  result_t r = sendMessage(data, len, /*is_binary=*/1);
  if (r == RESULT_OK)
    ESP_LOGI("IOT-SDK", "msg sent (binary) len=%u", (unsigned)len);
  else
    ESP_LOGW("IOT-SDK", "msg send failed: %d", r);
}

stopMessageChannel()

• The stopMessageChannel() function stops the local message channel: any queued messages are dropped and sending is disabled.
• This function takes no parameters.

note

Returns DATA_CHANNEL_NOT_STARTED if the channel was never started. You do not need to call this before leave(); leaving the meeting releases the message channel automatically.

Example

#include "videosdk.h"
#include "esp_log.h"
void app_main(){
  result_t r = stopMessageChannel();
  ESP_LOGI("IOT-SDK", "Stop Message Channel Result: %d", r);
}

API Reference

The API references for all the methods utilized in this guide are provided below.

• startMessageChannel
• sendMessage
• stopMessageChannel