Use this guide to quickly start a basic voice call with the Agora Voice SDK for Windows.

Sample projects

We provide the open-source sample projects that implement the video call on GitHub:

Before implementing a voice call, you can download the sample projects and refer to the source code.

Prerequisites

  • Microsoft Visual Studio 2017 or later
  • A Windows device running Windows 7 or later
  • A valid Agora account. (Sign up for free)
Open the specified ports in Firewall Requirements if your network has a firewall.

Set up the development environment

In this section, we will create a Windows project and integrate the SDK into the project.

Create a Windows project

Now, let's build a Windows project from scratch. Skip to Integrate the SDK if a Windows project already exists.

Create a Windows project
  1. Open Microsoft Visual Studio and click Create new project.
  2. On the New Project panel, choose MFC Application as the project type, input the project name, choose the project location, and click OK.
  3. On the MFC Application panel, choose Application type > Dialog based, and click Finish.

Integrate the SDK

Follow these steps to integrate the Agora Voice SDK into your project.

1. Configure the project files

  • Go to SDK Downloads, download the latest version of the Agora SDK for Windows, and unzip the downloaded SDK package.
  • Copy the x86 or x86_64 folder of the downloaded SDK package to your project files according to your development environment.

2. Configure the project properties

Right-click the project name in the Solution Explorer window, click Properties to configure the following project properties, and click OK.

  • Go to the C/C++ > General > Additional Include Directories menu, click Edit, and input $(SolutionDir)include in the pop-up window.
  • Go to the Linker > General > Additional Library Directories menu, click Edit, and input $(SolutionDir) in the pop-up window.
  • Go to the Linker > Input > Additional Dependencies menu, click Edit, and input agora_rtc_sdk.lib in the pop-up window.

Implement the basic call

This section introduces how to use the Agora SDK to make a voice call. The following figure shows the API call sequence of a basic one-to-one voice call.

1. Create the UI

Create the user interface (UI) for the one-to-one voice call in your project. Skip to Initialize IRtcEngine if you already have a UI in your project.

If you are implementing a voice call, we recommend adding the elements into the UI:

  • The end-call button

When you use the UI setting of the demo project, you can see the following interface:

2. Initialize IRtcEngine

Create and initialize the IRtcEngine object before calling any other Agora APIs.

In this step, you need to use the App ID of your project. Follow these steps to create an Agora project in Console and get an App ID.

  1. Go to Console and click the Project Management icon on the left navigation panel.
  2. Click Create and follow the on-screen instructions to set the project name, choose an authentication mechanism, and Click Submit.
  3. On the Project Management page, find the App ID of your project.

Call the createAgoraRtcEngine method and the initialize method, and pass in the App ID to initialize the IRtcEngine object.

You can also listen for callback events, such as when the local user joins the channel, and when the local user leaves the channel.

CAgoraObject *CAgoraObject::GetAgoraObject(LPCTSTR lpAppId)
{
    if (m_lpAgoraObject == NULL)
        m_lpAgoraObject = new CAgoraObject();
    if (m_lpAgoraEngine == NULL)
        // Create the instance.
        m_lpAgoraEngine = (IRtcEngine *)createAgoraRtcEngine();
    if (lpAppId == NULL)
        return m_lpAgoraObject;
    RtcEngineContext ctx;
    ctx.eventHandler = &m_EngineEventHandler;
#ifdef UNICODE
    char szAppId[128];
    ::WideCharToMultiByte(CP_ACP, 0, lpAppId, -1, szAppId, 128, NULL, NULL);
    // Input your App ID.
    ctx.appId = szAppId;
#else
    ctx.appId = lpAppId;
#endif
    // Initialize the RtcEngine object.
    m_lpAgoraEngine->initialize(ctx);
    return m_lpAgoraObject;
}
// Inherit the events and callbacks of IRtcEngineEventHandler.
class CAGEngineEventHandler :
    public IRtcEngineEventHandler
{
public:
    CAGEngineEventHandler(void);
    ~CAGEngineEventHandler(void);
    void SetMsgReceiver(HWND hWnd = NULL);
    HWND GetMsgReceiver() {return m_hMainWnd;};

    // Listen for the onJoinChannelSuccess callback.
    // This callback occurs when the local user successfully joins the channel.
    virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed);


    // Listen for the onLeaveChannel callback.
    // This callback occurs when the local user successfully leaves the channel.
    virtual void onLeaveChannel(const RtcStats& stat);


    // Listen for the onUserOffline callback.
    // This callback occurs when the remote user leaves the channel or drops offline.
    virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);
private:
    HWND        m_hMainWnd;
};

3. Join a channel

After initializing the IRtcEngine object, you can call the joinChannel method to join a channel. In this method, set the following parameters:

  • channelName: Specify the channel name that you want to join.

  • token: Pass a token that identifies the role and privilege of the user. You can set it as one of the following values:

    • NULL.
    • A temporary token generated in Console. A temporary token is valid for 24 hours. For details, see Get a Temporary Token.
    • A token generated at the server. This applies to scenarios with high-security requirements. For details, see Generate a token from Your Server.
    If your project has enabled the app certificate, ensure that you provide a token.
  • uid: ID of the local user that is an integer and should be unique. If you set uid as 0, the SDK assigns a user ID for the local user and returns it in the onJoinChannelSuccess callback.

For more details on the parameter settings, see joinChannel.

BOOL CAgoraObject::JoinChannel(LPCTSTR lpChannelName, UINT nUID,LPCTSTR lpToken)
{
    int nRet = 0;
#ifdef UNICODE
    CHAR szChannelName[128];
    ::WideCharToMultiByte(CP_UTF8, 0, lpChannelName, -1, szChannelName, 128, NULL, NULL);
    char szToken[128];
    ::WideCharToMultiByte(CP_UTF8, 0, lpToken, -1, szToken, 128, NULL, NULL);
    if(0 == _tcslen(lpToken))
        nRet = m_lpAgoraEngine->joinChannel(NULL, szChannelName, NULL, nUID);
    else
        // Join a channel with a token.
        nRet = m_lpAgoraEngine->joinChannel(szToken, szChannelName, NULL, nUID);
#else
    if(0 == _tcslen(lpToken))
        nRet = m_lpAgoraEngine->joinChannel(NULL, lpChannelName, NULL, nUID);
    else
        nRet = m_lpAgoraEngine->joinChannel(lpToken, lpChannelName, NULL, nUID);
#endif
    if (nRet == 0)
        m_strChannelName = lpChannelName;
    return nRet == 0 ? TRUE : FALSE;
}

4. Leave the channel

Call the leaveChannel method to leave the current call according to your scenario, for example, when the call ends, when you need to close the app, or when your app runs in the background.

BOOL CAgoraObject::LeaveChannel()
{
    m_lpAgoraEngine->stopPreview();
    // Leave the current channel.
    int nRet = m_lpAgoraEngine->leaveChannel();
    return nRet == 0 ? TRUE : FALSE;
}


void CAgoraObject::CloseAgoraObject()
{
    if(m_lpAgoraEngine != NULL)
        // Release the IRtcEngine object.
        m_lpAgoraEngine->release();
    if(m_lpAgoraObject != NULL)
        delete m_lpAgoraObject;
    m_lpAgoraEngine = NULL;
    m_lpAgoraObject = NULL;
}

Run the project

Run the project on your Windows device. You can hear the remote user when you successfully start a one-to-one voice call in your app.

Reference

When integrating the Agora Voice SDK, you can also refer to the following articles: