Vivox: How to: Send additional non-messaging data through the text messaging service

Text messages contain the ability to send additional non-messaging data through two string variables: application stanza namespace and application stanza body.

The application stanza namespace carries Uniform Resource Identifier (URI) reference information that identifies an XML namespace. This is used for labeling what kind of information you are sending in the application stanza body. For more information about how to format the URI, see the W3C documentation on XML Namespaces.

The application stanza body carries the data that is associated with the given application stanza namespace. If data is text, it must be UTF-8 encoded. If binary is needed, use base64 to encode with a maximum of 8k per message.

Note: This information is hidden from the player, and can only be accessed through the code.

You might need to hide messages if you are using them to only send data and are not intending to send visible messages. One method to accomplish this is to label your application stanza namespace accordingly. For example, you could have an application stanza namespace named "data:hidden" or "message:omit". You can then check for all messages that have the same application stanza namespace.

Note: Messages must contain data. You cannot send an empty message.

You can access the hidden data after it is received. By grabbing the message from a function that receives the message, you can access its application stanza body.

• Unreal
• Unity
• Core

Unreal application stanza body

The following examples detail how to send hidden data through text messages and access hidden data from messages in the Vivox Unreal SDK.

Send hidden data in group messages

FString Message = playerInput; //Hello World!
FString ApplicationStanzaNamespace =  TEXT("team:color");
FString ApplicationStanzaBody =  TEXT("red");
IChannelSession::FOnBeginSendTextCompletedDelegate SendChannelMessageCallback;

SendChannelMessageCallback.BindLambda([this, channelId, Message](VivoxCoreError Error) {

    if (VxErrorSuccess == Error) 
    {
        UE_LOG(LogVivoxGameInstance, Log, TEXT("Message sent to %s: %s \n"),*channelId.Name(), *Message);
    }

    return;
});

currentChannelSession.BeginSendText("", *Message, ApplicationStanzaNamespace, ApplicationStanzaBody, SendChannelMessageCallback);

Send hidden data in directed messages

FString Message = playerInput; //Hello World!
FString ApplicationStanzaNamespace =  TEXT("team:color");
FString ApplicationStanzaBody =  TEXT("red");
ILoginSession::FOnBeginSendDirectedMessageCompletedDelegate SendDirectedMessageCallback;

SendDirectedMessageCallback.BindLambda([this, accountName, message](VivoxCoreError error, const FString &request_id)
{
    if (VxErrorSuccess != error) 
    {
        UE_LOG(LogVivoxGameInstance, Error, TEXT("BeginSendDirectedMessage() returned %d:%s"), error, ANSI_TO_TCHAR(FVivoxCoreModule::ErrorToString(error)));
    }

    return;
});

currentLoginSession.BeginSendDirectedMessage(AccountId(VIVOX_VOICE_ISSUER, accountName, VIVOX_VOICE_DOMAIN), "", Message, ApplicationStanzaNamespace, ApplicationStanzaBody, SendDirectedMessageCallback);

Access hidden data from messages

if(textMessage.ApplicationStanzaNamespace == “team:color”)
{
    if(textMessage.ApplicationStanzaBody == “red”)
    {
        //font becomes red
    }
    else if(textMessage.ApplicationStanzaBody == “blue”)
    {
        //font becomes blue
    }
    else
    {
        //font becomes grey
    }
}

Related information

Unreal > Unreal API Reference Manual > Class List > IChannelSession

• BeginSendText()

Unreal > Unreal API Reference Manual > Class List > ILoginSession

• BeginSendDirectedMessage()

Unreal > Unreal API Reference Manual > Class List > ITextMessage

• ApplicationStanzaNamespace & ApplicationStanzaBody

Unity application stanza body

The following examples detail how to send hidden data through text messages and access hidden data from messages in the Vivox Unity SDK.

Send hidden data in group messages

string message = playerInput;  // "Hello world!"
string appStanzaNamespace = "team:color"; 
string appStanzaBody = teamColor;  // "red" or "blue"

currentChannelSession.BeginSendText("",message, appStanzaNamespace, appStanzaBody, ar =>
{
    try
    {
        session.EndSendText(ar);
    }

    catch (Exception e)
    {
         LogSystemError(e.Message);
         return;
    }
});

Send hidden data in directed messages

AccountId  _accountId = AccountId(TokenIssuer, name, Domain);
string message = playerInput;  // "Hello world!"
string appStanzaNamespace = "team:color";
string appStanzaBody = teamColor;  // "red" or "blue"

currentLoginSession.BeginSendDirectedMessage(_account, "", message, appStanzaNamespace, appStanzaBody, ar =>
{
    try
    {
        _currentUser.EndSendDirectedMessage(ar);
    }

    catch (Exception e)
    {
        LogSystemError(e.Message);
        return;
    }
});

Access hidden data from messages

if(textMessage.ApplicationStanzaNamespace == “team:color”)
{
    if(textMessage.ApplicationStanzaBody == “red”)
    {
        //font becomes red
    }
    else if(textMessage.ApplicationStanzaBody == “blue”)
    {
        //font becomes blue
    }
    else
    {
        //font becomes grey
    }
}

Related information

Unity > Unity API Reference Manual > Class List > IChannelSession

• BeginSendText()

Unity > Unity API Reference Manual > Class List > ILoginSession

• BeginSendDirectedMessage()

Unity > Unity API Reference Manual > Class List > IChannelTextMessage

• ApplicationStanzaNamespace
• ApplicationStanzaBody

Unity > Unity API Reference Manual > Class List > IDirectedTextMessage

• ApplicationStanzaNamespace
• ApplicationStanzaBody

Core application stanza body

The following example detail how to send hidden data through text messages and access hidden data from messages in the Vivox Core SDK.

Send hidden data in messages

string applicationStanzaNamespace = "team:color"; 
string applicationStanzaBody = teamColor; //"red" or "blue"

vx_req_account_send_message_t *req;
vx_req_account_send_message_create(&req);
req->account_handle = vx_strdup(accountHandle.c_str());
req->message_body = vx_strdup(message.c_str());
req->user_uri = vx_strdup(user.c_str());
req->application_stanza_namespace = vx_strdup(applicationStanzaNamespace);
req->application_stanza_body = vx_strdup(applicationStanzaBody);
IssueRequest(&req->base);

Access hidden data from messages

if(evt->type == evt_message)
{
    vx_evt_message *tevt = (vx_evt_message *)evt;
    if ( tevt->application_stanza_namespace == "team:color")
    {
        if( tevt->application_stanza_body == "blue")
        {
            //assign font blue
        }
        else if( tevt->application_stanza_body == "red")
        {
            //assign font red
        }
        else
        {
            //assign font grey
        }
    }
}

Related information

This example mimics the SDKSampleApp::HandleMessage(vx_message_base_t *msg) function. For more information, see the SDK Sample Application.