<div dir="ltr"><div dir="ltr">On Tue, Feb 25, 2020 at 4:43 AM Jean Aunis <<a href="mailto:jean.aunis@prescom.fr">jean.aunis@prescom.fr</a>> wrote:<br></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
  

    
  
  <div>
    <p>Hello,</p>
    <p>I recently opened a issue regarding SIP headers handling in
      inbound messages
      (<a href="https://issues.asterisk.org/jira/browse/ASTERISK-28755" target="_blank">https://issues.asterisk.org/jira/browse/ASTERISK-28755</a>).</p>
    <p>Besides that problem, I think there are inconsistencies in the
      data format provided by ARI for sending or receiving text
      messages, and also in the documentation. Actually there are 3
      different data formats for message variables:<br>
    </p>
    <p>1- to send a message, additional variables may be provided in a
      "variables" field. Its value must be a JSON object whose keys are
      the variable names, and values are the variable values, i.e:</p>
    <p><tt>...<br>
        "variables": { </tt><tt><tt>"My-Custom-Header": "the_value", </tt></tt><tt><tt>"Another-header":
          "another_value"</tt> }<br>
      </tt></p>
    <p>2- when a message is received, a TextMessageReceived is emitted,
      which contains a TextMessage which then contains a "variable"
      field. This field is a list of JSON objects, each one containing a
      single key (the variable name) with its value :</p>
    <p><tt>...<br>
        "variables": [{ "My-Custom-Header": "the_value" }, {
        "Another-header": "another_value" }]</tt><br>
    </p>
    <p>(This is what I saw after quick-fixing the issue stated above)</p>
    <p>3- the behaviour described in (2) is not consistent with the ARI
      documentation, which states:</p>
    <p>TextMessageVariable: A key/value pair variable in a text message.<br>
      <br>
          key: string - A unique key identifying the variable.<br>
          value: string - The value of the variable.<br>
    </p>
    <p>So I would expect the variable field to look like the following:</p>
    <p><tt>...<br>
        "variables": [{ "key": "My-Custom-Header", "value": "the_value"
        }, { "key": "Another-header", "value": "another_value" }]</tt></p>
    <p>I personally think formats (1) and (3) both make sense, but I
      find format (2) not very practical to use. Any thoughts on the
      subject ?</p></div></blockquote></div><div> I could never get (2). When trying to send variables in the TextMessageReceived event I would get a validation error unless they are formatted like (3).</div><div><br></div><div>(3) is the currently declared documented way to to it. As such any other way breaks the API definition. However, when executing a sendMessage (1) is the way it is currently working, so I'd be worried about breaking current implementations if we altered it to (3) for that case.</div><div><br></div><div>So what to do?</div><div><br></div><div>Option A: Leave sendMessage as is (1), update the documentation for it, and fix TextMessageReceived to send variables as defined like (3). Least breaking, but inconsistent way of sending and receiving variables. </div><div><br></div><div>Option B: Update sendMessage to pass a TextMessageVariable like (3), and fix TextMessageReceived to send variables like (3). The current API definition doesn't change, but may break implementations.</div><div><br></div><div>Option C: Leave sendMessage as is (1), update the TextMessageVariable API definition to be similar to (1), e.g { "var name": "var value" }, and not { "key": "var name", "value": "var value" }. This of course breaks the current API definition, and would break implementations if the validation error did not occur.<br></div><div><br></div><div>While "A" is the safest (least breaking?), personally, I prefer and choose "C". While it does break the API it seemingly has not worked since the start so I don't think this will break any current implementations. It will also make sending and receiving variables more consistent.</div><div><br></div><div>Thoughts?</div><div><br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr">Kevin Harwell<div>Software Developer</div><div>Sangoma Technologies<br><div>Check us out at: <a href="https://sangoma.com/" target="_blank">https://sangoma.com</a> & <a href="https://asterisk.org" target="_blank">https://asterisk.org</a></div></div></div></div></div></div></div></div>