Enable Connect Group Chats

How Shout Connect Group Chats Work

One of the most important functions of a high performing affiliate and independent distributor business model is effective team communication. However, most organizations rely on free tools such as Facebook, Instagram, Messenger, WhatsApp, and Telegram to manage their team communication. Each of these tools require extensive manual effort to maintain effective team communication and then they are subject to algorithms and facebook jail for delivery push notifications to their team members. Shout Connect enabled group chats take the manual work out of team communication and ensure affiliates and distributors get connected with their teams.

Before You Get Started

If you've skipped over the preceding Shout guides ( no worries, we don't always read everything first either 😉), here are a few things that you'll want do before you open up your code and enable Connect Group Chats:

1. Make sure you or your organization has Shout Connect enabled on their account. If you're not sure, login to your Shout account and navigate to Settings > Services > Shout Connect. If you aren't able to access the Shout Connect page, reach out to Shout support (for production environments) or Shout Developers (for development environments) and ask to have it enabled for your organization first.
2. Check out our guide for setting up a development environment for easy testing and troubleshooting. You'll need api credentials.
3. Make sure that you have at least one other shout account that has authorized your Shout Connect account. You can read more about this in the Shout Connect Overview.

Step-By-Step Enabling Connect Orders and Text Alerts

There are four steps to enabling Connect Orders and Text Alerts. These steps are explained in detail with code examples below.

1. Add an affiliates existing team members
2. (Optional) Notify the connected account that their team members have been added
3. (Optional) Periodically add new team members
4. (Optional) Customize the plugin and simple connect page to allow affiliates and distributors to create and manage Connect Group Chats

Step 1: Add an affiliates exiting team members to their connected account.

We recommended doing this as soon as you receive the webhook api_client_granted_created event, but you can also iterate through all of your affiliates one by one if it's easier for your work flow. Here's how to add a single team member to a Connected Group Chat. You can use a simple for loop in your language of choice to iterate through multiple team members:

1. Construct the payload for the Upsert Connect User api call.
2. Include the connect_id of the team member AND the parent_connect_id for the connect user whose team you are adding.
3. Post to the Upsert Connect User endpoint.

{
  "upsert_connect_user": {
    "connect_id": "abc123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "parent_connect_id": "def123",
    "phone_number": "(435) 555-1234"
  }
}

curl https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user -X POST \
-u username:password \
-d "{\"upsert_connect_user\":{\"connect_id\":\"abc123\",\"email\":\"jane@example.com\",\"name\":\"Jane Smith\",\"parent_connect_id\":\"def123\",\"phone_number\":\"(435) 555-1234\"}}"

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user")
uri.query = {"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}}
request = Net::HTTP::Post.new(uri)
request.basic_auth("username", "password")
request.body = JSON.dump({"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}})

req_options = { use_ssl: uri.scheme == "https" }

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

import requests
from requests.structures import CaseInsensitiveDict

url = "https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user"

headers = {
  "Content-Type": "application/json",
}
data = '{"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}}'

response = requests.post(url, headers=headers, data=data, auth=('username', 'password'))

print(response.status_code)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"upsert_connect_user\":{\"connect_id\":\"abc123\",\"email\":\"jane@example.com\",\"name\":\"Jane Smith\",\"parent_connect_id\":\"def123\",\"phone_number\":\"(435) 555-1234\"}}");

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_USERPWD, 'username' . ':' . 'password');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
  echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import javax.xml.bind.DatatypeConverter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

  public static void main(String[] args) throws IOException {
    URL url = new URL("https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user");
    HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
    httpConn.setRequestMethod("POST");

    byte[] message = ("username:password").getBytes("UTF-8");
    String basicAuth = DatatypeConverter.printBase64Binary(message);
    httpConn.setRequestProperty("Authorization", "Basic " + basicAuth);

    httpConn.setDoOutput(true);
    OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
    writer.write("{\"upsert_connect_user\":{\"connect_id\":\"abc123\",\"email\":\"jane@example.com\",\"name\":\"Jane Smith\",\"parent_connect_id\":\"def123\",\"phone_number\":\"(435) 555-1234\"}}");
    writer.flush();
    writer.close();
    httpConn.getOutputStream().close();

    InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
    Scanner s = new Scanner(responseStream).useDelimiter("\A");
    String response = s.hasNext() ? s.next() : "";
    System.out.println(response);
  }
}

var request = require('request');

var headers = {
};

var dataString = '{"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}}';

var options = {
    url: 'https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user',
    method: 'POST',
    headers: headers,
    body: dataString,
    auth: {
        'user': 'username',
        'pass': 'password'
    }
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

package main

import (
  "fmt"
  "io/ioutil"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}}`)
  req, err := http.NewRequest("POST", "https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user", data)
  if err != nil {
    log.Fatal(err)
  }
  req.SetBasicAuth("username", "password")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.shout.app/api/v20230615/connect_clients/CONNECTCLIENTID/upsert_connect_user"))
    {
        var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("username:password"));
        request.Headers.TryAddWithoutValidation("Authorization", $"Basic {base64authorization}"); 


        request.Content = new StringContent({"upsert_connect_user":{"connect_id":"abc123","email":"jane@example.com","name":"Jane Smith","parent_connect_id":"def123","phone_number":"(435) 555-1234"}});
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded");

        var response = await httpClient.SendAsync(request);
    }
}

Step 2: Notify the connected account that team members have been added

Although optional, it's best practice to notify affiliates and distributors that you've added a team member to their account. This ensures that they are aware that invites will be sent (if they have them enabled) and allows them to be prepared to handle onboarding questions. Shout Connect makes sending this notificaiton very simple. You'll simply post a message to the /messages/send_connect_notification with the connect_id or shout user_id. Here's a simple example:

1. Construct the payload for the Send Shout Notification api call.
2. Include the API credentials header in your call. Check out the documentation here for more information.
3. Post to the Send Connect Notification or Send Broadcast Message endpoint.

{
  "message": {
    "body": "A new member has joined your team.",
    "user_id": 315
  }
}

curl https://www.shout.app/api/v20230615/messages/send_connect_notification -X POST \
-u username:password \
-d "{\"message\":{\"body\":\"A new member has joined your team.\",\"user_id\":315}}"

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://www.shout.app/api/v20230615/messages/send_connect_notification")
uri.query = {"message":{"body":"A new member has joined your team.","user_id":315}}
request = Net::HTTP::Post.new(uri)
request.basic_auth("username", "password")
request.body = JSON.dump({"message":{"body":"A new member has joined your team.","user_id":315}})

req_options = { use_ssl: uri.scheme == "https" }

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

import requests
from requests.structures import CaseInsensitiveDict

url = "https://www.shout.app/api/v20230615/messages/send_connect_notification"

headers = {
  "Content-Type": "application/json",
}
data = '{"message":{"body":"A new member has joined your team.","user_id":315}}'

response = requests.post(url, headers=headers, data=data, auth=('username', 'password'))

print(response.status_code)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.shout.app/api/v20230615/messages/send_connect_notification');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"message\":{\"body\":\"A new member has joined your team.\",\"user_id\":315}}");

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_USERPWD, 'username' . ':' . 'password');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
  echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import javax.xml.bind.DatatypeConverter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

  public static void main(String[] args) throws IOException {
    URL url = new URL("https://www.shout.app/api/v20230615/messages/send_connect_notification");
    HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
    httpConn.setRequestMethod("POST");

    byte[] message = ("username:password").getBytes("UTF-8");
    String basicAuth = DatatypeConverter.printBase64Binary(message);
    httpConn.setRequestProperty("Authorization", "Basic " + basicAuth);

    httpConn.setDoOutput(true);
    OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
    writer.write("{\"message\":{\"body\":\"A new member has joined your team.\",\"user_id\":315}}");
    writer.flush();
    writer.close();
    httpConn.getOutputStream().close();

    InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
    Scanner s = new Scanner(responseStream).useDelimiter("\A");
    String response = s.hasNext() ? s.next() : "";
    System.out.println(response);
  }
}

var request = require('request');

var headers = {
};

var dataString = '{"message":{"body":"A new member has joined your team.","user_id":315}}';

var options = {
    url: 'https://www.shout.app/api/v20230615/messages/send_connect_notification',
    method: 'POST',
    headers: headers,
    body: dataString,
    auth: {
        'user': 'username',
        'pass': 'password'
    }
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

package main

import (
  "fmt"
  "io/ioutil"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"message":{"body":"A new member has joined your team.","user_id":315}}`)
  req, err := http.NewRequest("POST", "https://www.shout.app/api/v20230615/messages/send_connect_notification", data)
  if err != nil {
    log.Fatal(err)
  }
  req.SetBasicAuth("username", "password")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.shout.app/api/v20230615/messages/send_connect_notification"))
    {
        var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("username:password"));
        request.Headers.TryAddWithoutValidation("Authorization", $"Basic {base64authorization}"); 


        request.Content = new StringContent({"message":{"body":"A new member has joined your team.","user_id":315}});
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded");

        var response = await httpClient.SendAsync(request);
    }
}

Step 3: Periodically Add New Team Members

Although optional, it's very helpful to add new team members to connected accounts so that affiliates and distributors can easily manage team onboarding and keep their communication and teams up to date. You'll simply follow the example as Step 1 above. Shout Connect will also intuitively update records for you. For example, if an affiliate changes team, you simply need to post their updated parent_connect_id with the same connect_id and Shout will update the team that the affiliate is available to. You'll want to notify folks of these types of changes so that they can then manage their group chats accordingly (Shout Connect won't automatically remove folks from their prior team's group chats, the team leader will need to do that manually).

Step 4: Customize the plugin and simple connect page to allow affiliates and distributors to create and manage Connect Group Chats

Shout Connect makes it easy to access and manage Connect Group Chats directly from the Simple Connect Page and Connect Plugin. You'll just need to enable the feature on your Connect Account:

1. Login to your Shout account and navigate to your Shout Connect services Page by clicking on Settings > Services > Shout Connect. If the page is not visible contact Shout support to have it enabled on your account.
2. Click the "Manage" button and then click Edit to open the settings modal
3. Click the "Chat with Team Tab" switch to the "On" position
   
4. Scroll down and click "Save"