How to send a message to multiple recipients via Conversations API?

[ajmccann]

I can send a message to a single user via the Conversations API - using PHP:

Snippet of PHP with a user hardcoded for testing:

$post = [
'recipients[]' => '256',
// 'recipients[]' => 'recipients[]=249&recipients=256',
'group_conversation' => true,
'bulk_message' => true,
'subject'=>$msg_subject,
'body'=>$msg_body,
];

var_dump($post);

// $header = array("Authorization: Bearer {$access_token}");

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $token_url,
CURLOPT_HTTPHEADER => $header,
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $post,
CURLOPT_RETURNTRANSFER => true
));
$lti_msgresponse = curl_exec($curl);
curl_close($curl);
echo($lti_msgresponse);

The documentation for the API is:

Conversations - Canvas LMS REST API Documentation 

recipients[] Required string
An array of recipient ids. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

This comes across as doublespeak to me: it's a string...but it's an array?

I've tried following the slender documentation - to send two user IDs. But I get "invalid recipient as a response using:

'recipients[]' => 'recipients[]=249&recipients=256',

I've tried passing a nested array

$arrTempRecip = array(
array('recipients[]'=>249),
array('recipients[]'=>256)
);

Then using: 

'recipients[]' => arrTempRecip,

But PHP complains about converting an array to a string in the CURLOPT section.

The very end of this Google Groups conversation touches on the issue...but the solution isn't spelled out and I'm not putting the pieces together.

Since the API requires a string, not an array, I think it's something closer to "recipients[]=249&recipients=256"...very frustrating!

Help/guidance appreciated. Lots of Canvas APIs use this [] construction and I'm just not getting it. exclude[], attachments[]...

[James · Accepted solution]

 @ajmccann  

I would say there's a typo in the documentation. It should be recipients[]=1&recipients[]=2&recipients[]=course_3

The recipients[] required string means that it is an array whose values are strings.  You're free to send integers, but it needs to be string to handle values like course_3.

To send to the two IDs 249 and 246, it should look like this:

In JSON, it would be { "recipients" : [ 249, 256 ] }

I'm doing this without testing, but you might try 'recipients[]' => array(249, 256)

If that doesn't work, try 'recipients' => array(249, 256).

I wish I could be more definite, but I use PHP to usually convert the POSTS payload to JSON and send it that way. However, some of my code does have the [] as part of the field name, so I would start with recipients[] and not recipients.

[ajmccann]

James,

"Luminary" doesn't begin to describe it (your status in the Community)!

Many thanks for reading and replying - on a national holiday no less.

You are right:

• Typo in the documentation
• Correct answer is:
  • recipients[] => 249
    • For one value
  • recipients => (249,26,79) 
    • For multiple values

What I tried to do, hours earlier, was:

• recipients[] => (249,26,79)

I don't understand why this would NOT work.

Also, weirdly, the following works for two values - but no more.

• recipients[] => 249
• recipients => 26

Canvas APIs are amazing...so I won't hold a grudge. But that documentation was some classic technical writing nightmare example stuff!

Happy Holidays and here's to a wonderful 2020...!

[James]

recipients[] => array(249,26,79)

The http_build_query() function in PHP converts an array and adds the [] for you. The recipients[] => array(249,26,79) would turn into recipients[][]=249&recipients[][]=26&receipients[][]=79. It would encode the [ and ] as %5B and %5D, making it harder for humans to read. A closer look at my code (I'm on vacation and don't have access to all of it) shows that I used the [] only when I was a passing a single value.

This is a POST, not a GET. You're using CURLOPT_POSTFIELDS and the documentation there is a little less obvious. It says you can pass the information as an urlencoded string or an array of values. It doesn't say, at least not there, what happens to an array within an array.  Some of the comments on that page from 7 to 9 years ago say that it doesn't handle multidimensional arrays. Various comments in other places say that you should pass nested arrays through http_build_query before sending it to CURL -- unless you're trying to send a file, in which case you need to manually create the request parameters.