Sending messages via the Conversations API

[mzimmerman]

I am taking my first fumbling steps at scripting using the Rest APIs, so please be gentle!

We have a survey coming up that will require us to send out individual/unique survey links to students, and are hoping to use the Canvas Inbox/Conversations as one channel for distributing them.  I'm also trying to get my feet wet with the APIs and scripting.

To get a feel for how this might work, I'm playing with the Canvas Live API.  I've been able to do other things like creating courses via the API, and I can retrieve a list of conversations, but am having trouble creating a new conversation via the API.

I'm filling in the Live API form with recipients as just the numeric canvas_id, or spelling out "recipients[]=<id>", but neither seems to work.  The response I'm getting back is:

"There was a problem with your last request. You may have tried to perform an action after a long period of inactivity. If that's the case, try going back, reloading the page you were working on, and resubmitting. If not, please let us know what you were doing when the error happened."

The response headers say:

"Connection": "keep-alive",
"Content-Length": "19496",
"Content-Type": "text/html; charset=utf-8",
"Date": "Fri, 19 Oct 2018 17:13:17 GMT",
"P3p": "CP=\"None, see http://www.instructure.com/privacy-policy\"",
"Server": "Apache",
"Status": "422 Unprocessable Entity",
"X-Canvas-Meta": "q=739;",
"X-Content-Type-Options": "nosniff",
"X-Request-Context-Id": "b0807f1e-d432-4d0e-88bc-431889a8cce4",
"X-Request-Processor": "00128f213e1b667ff",
"X-Runtime": "0.098474",
"X-Session-Id": "fbb6af825b6850c61a85e1f3a03d448a",
"X-Ua-Compatible": "IE=Edge,chrome=1",
"X-Xss-Protection": "1; mode=block"

The admin user who's sending the message (and whose access token I'm using) can send messages to this recipient via the GUI without specifying a course, so that doesn't seem to be the issue.  Is there something else I'm missing about creating messages with the Conversations API?

Thanks!

[robotcars]

Hi Michael,

I was not able to format an API request using the Live API either when I tried doing a similar project.

I just got the same error trying again.

422 Unprocessable Entity, means that the server understood the request (endpoint) but didn't like your formatted data.

Have you tried the request in something like POSTMAN or even jQuery in the browser just to work with the parameter settings? I know I often have trouble getting the parameters configured correctly between different languages and libraries.

The conversations API can be a little frustrating, because Canvas by default wants to associate conversations to a course closest to the users in the conversation. Sending unique conversations, especially with a Subject line, to each student without automatic associations is not documented.

Conversations API: How to create messages with a new subject 

How many recipients are you sending to?

I found the best way was to loop through either an api result set or db result and send each student a conversation.

/api/v1/conversations?recipients=123&subject=Subject&body=Message&bulk_message=true&group_conversation=true

What language are you writing in?

I have some Ruby code that automates our Nudge, that I can strip down to a basic example.

[mzimmerman]

Thanks, Robert.

The link to your previous discussion is helpful.  I'll have to play with the group_conversation=true and bulk_message=true settings

This is a message that will have to be sent to several thousand students, which is why we're trying to script it.  However, each student gets a different message body, since the message will contain a unique survey link for that particular student.  Thus, the plan is to loop through a csv file with the users/links and make an individual call to the Conversations API for each one, so group message settings are kind moot.  

At this point, I have no idea what to write it in, since I'm a development newbie.  Probably bash or python, since I'm working on a Mac, but I'm open to suggestions....

Mike

[robotcars]

I'm working on a Mac too, dev on Mac, run production code on RedHat. I feel I end up writing less code with Ruby, finding more available resources, and being able to read Canvas source code easier. Python is also popular and there are a lot of Python developers lurking around here.

Our SIS import is in Bash, it's fun, it's nice to use all the built in command line tools to empower those scripts, but modern library dependencies make this SOOO much easier, like Ruby gems, Node and Python modules.

There are several options for installing Ruby on Mac. Using Python on Mac is easy because it becomes preinstalled, but if you find yourself wanting some new modules or updating python you'll want to install a separate copy from the system copy otherwise you could create some issues for OSX.

Honestly, you can't go wrong with either choice, and if you're 'new' just go with the one you're most comfortable with and that you find the most resources for.

[agschmid]

Hi Michael,

The reason to use group_conversations=true is so the conversation can have a new subject. If you don't use group_conversations, if there was ever a conversation between the sender/recipient, the old subject gets re-used.

[mzimmerman]

Thanks for all the help, everyone!  

I never did get anything working with the Live API, but with the assistance of my Lincoln colleague  @hosier ‌, I have a script that can parse a CSV file for student IDs and survey URLs, extract the Canvas user ID for each student, then post individual messages to each student's Canvas inbox with the appropriate survey link for that student.

I was having trouble with the subject field until I went back to carroll-ccsd‌'s post and added the group_conversation=true setting.

I worked in Python, and I'm sure someone else could write better Python code, but it's definitely been fun getting the hang of coding against the Canvas APIs!

[robotcars]

All the credit for that goes to agschmid‌ for finding and sharing the undocumented solution.