Using Erlang's =maps:groups_from_list/2= function

Since OTP 25, Erlang has included a function maps:groups_from_list/2 and I had occasion to use it recently.

In KAZOO, we have a process that monitors other processes, keeping track of their message queue length, heap size, etc (we're on OTP 26 at the moment so need to do this manually).

I wanted to print a table of the tracked processes, ordered first by message queue length, but within the group, sorted by heap size. 

-record(proc_info, {pid, message_queue_len, total_heap_size}).

sort_processes(Processes) ->
    %% Groups = #{mql => [#proc_info{}...]
    Grouped = maps:groups_from_list(fun(#proc_info{message_queue_len=MQL}) -> MQL end
				   ,Processes
				   ),
    maps:fold(fun sort_group_by_heap/3, [], Grouped).

sort_group_by_heap(_MQL, ProcInfos, Acc) ->
    lists:keysort(#proc_info.total_heap_size, ProcInfos) ++ Acc.

The first argument is used to extract the each list element a "key" to use when inserting the element into the resulting map. In my case, the grouping was for message_queue_len.

The Grouped map() will contain keys corresponding to the unique set of message queue lengths, and the value will be the list of #proc_info{} records.

There is an arity-3 version where you can map the list element into a new value to be put into the grouping's list of results as well. As I want to sort the records by total_heap_size after grouping, I had no cause to use it.

What I like about Erlang records

Records get a bad rap in Erlang, especially now that maps exist. I find the utility of records to be so great that I reach for them way more often than for maps when I have a fixed amount of fields. Records work really well with the lists:key* functions to, providing the index into the record tuple as above in sort_group_by_heap.

One day I'll write more about how I use records but wanted to mention this specific use as a common one in my work.

Reverse binaries in Erlang

Reversing binaries in Erlang

In KAZOO, we have a kz_binary module that performs various functions over binary() data (typically string-ish stuff). Most of this code came before the string module was introduced in OTP 20 (for those that may not be aware, KAZOO started on R15B03 in 2010).

Recently we encountered an issue in a production cluster where a large blob of JSON was being processed and kz_binary:strip_right/2 was called to remove trailing endlines (why is a longer story related to changes in how we are receiving data from an external service that haven't been reflected yet in KAZOO's reception of the data) and getting stuck.

strip_right reverses the binary() and removes the supplied character, then reverses the result back. The existing reverse/1 implementation was cribbed from a Stack Overflow answer:

Existing implementation

reverse(Binary) ->
    Size = byte_size(Binary) * 8,
    <<X:Size/little-integer>> = Binary,
    <<X:Size/big-integer>>.

This works great until Binary gets large. In testing, if the binary() is large (222 (4194304) bits or 219 (524288) bytes), this binary matching will fail. Coincidentally, the JSON blob was 562868 bytes and triggered the crash.

After updating the tests to include a large enough binary to stress the code, I tried a couple different approaches before settling on chunking the binary input up, reversing the chunks into an accumulator, and converting that list of chunks back into a binary.

New implementation - reverse the chunks

%% for large binaries, we need to chunk them up and reverse them
%% REV_CHUNK was chosen because #reasons (through experiments)
-define(REV_CHUNK, 8192).

-spec reverse(binary()) -> binary().
reverse(<<Front:?REV_CHUNK/integer-little, Rest/binary>>) ->
    list_to_binary(reverse(Rest, [<<Front:?REV_CHUNK/integer-big>>]));
reverse(Binary) ->
    %% this fails for large binaries
    Size = bit_size(Binary),
    <<X:Size/little-integer>> = Binary,
    <<X:Size/big-integer>>.

%% side note: it was observed that creating a binary as the
%% accumulator caused execution time to range 30-60ms while using the
%% list as accumulator and converting to binary at the end caused
%% execution time to range 1-6ms typically, hence the list of binaries here
reverse(<<Front:?REV_CHUNK/integer-little, Rest/binary>>, Acc) ->
    reverse(Rest, [<<Front:?REV_CHUNK/integer-big>> | Acc]);
reverse(Rest, Acc) ->
    [reverse(Rest) | Acc].

REV_CHUNK was chosen through some experiments with timer:tc/3 running but there wasn't that much variability. A better perf test might settle on a better power of 2 but at the time, no meaningful reduction in time was observed on the dev machine used.

One other interesting note was using a list for the accumulator vs constructing the resulting binary (eg <<Front/binary, Acc/binary>> in reverse/2) was much faster.

Do note that this approach doesn't take into account Unicode stuff like grapheme clusters (see the Erlang string description and Using Unicode in Erlang for more). Caveat emptor!

Why I enjoy Erlang

I want to highlight two bits of the code above that I appreciate about Erlang that may not be apparent to some.

  • Clause ordering

    First, the order of clauses in the reverse/1 provide some assurances:

    • We know that any binary() input that has ?REV_CHUNK bytes (or more) will be handled in the first clause
    • Because of that, we know that Binary in the second clause must be smaller than ?REV_CHUNK bytes.

    This is a powerful approach I use a lot in Erlang - using clauses to match arguments as specifically as possible. The code is self-documenting on how to handle large vs small binaries (and what "large" is defined as). Recursive functions are easily defined by stating the base case in the first clause (or clauses) and the recursive part as the last clause.

    For instance, also from kz_binary: 

    pos(Char, Bin) ->
    pos(Char, Bin, 0).

pos(_Char, <<>>, _Pos) -> -1;
pos(Char, <<Char, _/binary>>, N) -> N;
pos(Char, <<_, Bin/binary>>, N) ->
    pos(Char, Bin, N + 1).
    1. First clause of pos/3 says we reached the end of Bin and didn't find Char
    2. Second clause says we found Char and return the position it was found
    3. Third clause does the recursion, taking the first byte off Bin and incrementing the position
  • List construction via prepend

    Prepending elements onto a list is fast and gives Erlang a natural stack data structure. If we look at a trace of how reverse/2 works we can see how elegantly the list construction helps create the solution:

    With REV_CHUNK=32 (4 8-byte chunks) when calling kz_binary:reverse(<<"abcdefghijkl">>):

    Function Front Rest Acc
    rev/1 1684234849 <<"efghijkl">>  
    rev/2 1751606885 <<"ijkl">> [<<"dcba">>]
    rev/2 1818978921 <<>> [<<"hgfe">>,<<"dcba">>]
    rev/2   <<>> [<<"lkji">>,<<"hgfe">>,<<"dcba">>]

    list_to_binary([<<"lkji">>,<<"hgfe">>,<<"dcba">>]) => <<"lkjihgfedcba">>

    Of course, this is a manually-written fold. Conceptually the code works the same as: 

    reverse(Binary) ->
    lists:foldl(fun(<<Nib:?REV_CHUNK/big>>, Acc) -> [Nib | Acc] end
	       ,[]
	       ,[Bin || <<Bin:?REV_CHUNK/little>> <= Binary] % obviously assumes binary has even number of REV_CHUNK chunks
	       ).

Alternative approaches

I looked at some other approaches and found them to be lacking.

Simple reverse using binary accumulator: 

%% this one took 9007807 (or 9 seconds) on the big input
reverse(Binary) ->
    reverse(Binary, <<>>).

reverse(<<>>, Acc) -> Acc;
reverse(<<H:1/binary, Rest/binary>>, Acc) ->
    reverse(Rest, <<H/binary, Acc/binary>>).

Using lists:reverse/1: 

%% this took a range of 15..64 ms on the big input
reverse(Binary) ->
    list_to_binary(lists:reverse(binary_to_list(Binary))).

2025-03-28: Newer version of reverse/1

Of course, while writing this post, I was doing some more reading in the Erlang docs and found that, apparently since R14B, the binary module contains encode_unsigned/2 and decode_unsigned/2 functions! 

reverse(Binary) ->
    binary:encode_unsigned(binary:decode_unsigned(Bin, 'big'), 'little').

How lovely! I always like when we can leverage core Erlang code over home-rolled solutions. We have more than enough in KAZOO and I hope we can continue to weed it out where approriate.

Bomber

It seems like most kids in the late 80s / early 90s played BOMBER on the Apple 2e.

The basic premise of the game was answering basic multiplication questions to earn more bombs, fuel, rounds, and stealth mode. You then got to control a plane (side-scrolling) as it flew along the mission route. Enemy pilots will try to shoot you while you have to bomb specific targets without being hit and before you lose your fuel.

This forum proved to have the keys to finding the disk image of the game (was a suite of games really, but BOMBER was the one I remember best).

You'll want to download the DSK file, then use an emulator to run the disk and play the game.

#nostalgia

Advent of Code 2020 - Day 2

AoC 2020 Day 2

Day 2 of the Advent of Code evaluates a string against a rule for validity.

Reading the input

read_input(File) ->
    {'ok', Lines} = file:read_file(File),
    [line_to_pw(Line) || Line <- binary:split(Lines, <<"\n">>, ['global']), Line =/= <<>>].

line_to_pw(Line) ->
    {'match', [Min, Max, Char, PW]} = re:run(Line, <<"(\\d+)-(\\d+)\s+(\\w):\s+(.+)$">>, [{'capture', 'all_but_first', 'binary'}]),
    {binary_to_integer(Min, 10), binary_to_integer(Max, 10), Char, PW}.

Here we utilize a regular expression to capture the Min and Max numbers (\d+ - 1 or more digits), the character the limits apply to (\w - just one character), and the password to validate ((.+) everything after the space until the end of the string).

Evaluating passwords

main(_) ->
    PasswordDB = read_input("p2.txt"),
    Valid = lists:foldl(fun count_valid_pw/2, 0, PasswordDB),
    io:format('user', "valid: ~p~n", [Valid]).

count_valid_pw({Min, Max, Char, PW}, ValidCount) ->
    case is_valid_pw(Min, Max, Char, PW) of
	'true' -> ValidCount + 1;
	'false' -> ValidCount
    end.

is_valid_pw(Min, Max, Char, PW) ->
    Count = length(binary:split(PW, Char, ['global']))-1,
    Count >= Min andalso Count =< Max.

After loading the passwords and rules into PasswordDB, we fold over the list and count only those passwords that are valid.

To validate the password, I chose to split the password on the Char value, get the length of the list and decrement by one. For instance: 

binary:split(<<"aaa">>, <<"a">>, ['global']).
[<<>>,<<>>,<<>>,<<>>]
Count = 3

binary:split(<<"cdefg">>, <<"b">>, ['global']).
[<<"cdefg">>]
Count = 0

binary:split(<<"ccccccccc">>, <<"c">>, ['global']).
[<<>>,<<>>,<<>>,<<>>,<<>>,<<>>,<<>>,<<>>,<<>>,<<>>]
Count = 9

Then it is a simple check on Min <= Count <= Max.

Part 2

The big change for part 2 is the is_valid_pw/4 function: 

is_valid_pw(FirstPos, SecondPos, Char, PW) ->
    case {char_at(FirstPos, PW), char_at(SecondPos, PW)} of
	{Char, Char} -> 'false';
	{Char, _} -> 'true';
	{_, Char} -> 'true';
	{_, _} -> 'false'
    end.

char_at(Pos, PW) ->
    erlang:binary_part(PW, Pos-1, 1).

Min and Max are re-interpreted as FirstPosition and SecondPosition. We get the character at each position and compare to Char. I explicitly show the truth table via pattern matching on Char but it is effectively an xor operation. See for example: 

33> (<<"c">> =:= <<"c">>) xor (<<"c">> =:= <<"c">>).
false
34> (<<"b">> =:= <<"c">>) xor (<<"c">> =:= <<"c">>).
true
35> (<<"c">> =:= <<"c">>) xor (<<"c">> =:= <<"b">>).
true
36> (<<"b">> =:= <<"c">>) xor (<<"c">> =:= <<"b">>).
false

Wrap-up

Not much trouble on this one. Getting the regexp right made the rest mostly took care of itself. Execution time for both parts remains ~0.180s.

Advent of Code 2020 - Day 1

AoC 2020 Day 1

Day 1 of the Advent of Code brings us a search problem - find two entries whose sum is 2020 and answer with the product.

Reading the input file

I like to get the data in from the file and into a workable internal format. For this problem its pretty simple - a list of integers will suffice. 

read_input(File) ->
    {'ok', Lines} = file:read_file(File),
    [binary_to_integer(Line, 10) || Line <- binary:split(Lines, <<"\n">>, ['global']), Line =/= <<>>].

Were the test file larger, file:read_line/1 could be used instead; as-is, let's read the whole file into a binary.

Next, I used binary:split/3 to break the binary into a list of binaries broken on the end line. Sometimes files have an extra end line so filter any Line that is an empty binary.

Since we know each Line should contain an integer, use binary_to_integer(Line, 10) to explicitly convert from a base-10 encoded integer (vs <<"1F">> which would necessitate using 16 instead).

Processing the list

Now that we have a list of integers, we need to find the two entries whose sum is 2020. Naively, we can take the head of the list and iterate over the tail of the list looking for the winning sum. 

main(_) ->
    [H|Input] = read_input("p1.txt"),
    {X, Y} = find_2020(Input, H),
    io:format("answer: ~p~n", [X*Y]).

find_2020(Input, H) ->
    case foldl(Input, H) of
	{X, Y} -> {X, Y};
	'undefined' -> find_2020(tl(Input), hd(Input))
    end.

foldl([], _) -> 'undefined';
foldl([Y|_], X) when X+Y =:= 2020 -> {X, Y};
foldl([_|T], X) -> foldl(T, X).

I decided to manually roll a fold that terminates early when the match is found.

First we pop the head of the list ([H|Input] = read_input(...)). Next we fold over the tail of the list (Input) looking for an item in the list that sums to 2020 with our H. If we exhaust the list (first clause of foldl/2) we return the atom undefined and recursively call find2020/2 with the head and tail of the list.

To get an idea of what this looks like in practice, suppose a list of [1, 2, 3]; find_2020/2 would evaluate like: 

[1 | [2, 3]] = read_input(...),
find_2020([2, 3], 1).

find_2020([2, 3], 1) ->
  foldl([2, 3], 1).

foldl([2 | [3]], 1) -> foldl([3], 1).
foldl([3 | []], 1) -> foldl([], 1).
foldl([], 1) -> 'undefined'.

find_2020([3], 2).

foldl([3 | []], 2) -> foldl([], 2).
foldl([], 2) -> 'undefined'.

find_2020([], 3).

foldl([], 3) -> 'undefined'.

This effectively searches every combination until the solution is found. Solutions of O(n^2) complexity are typically not what one might aspire to use when solving problems, but in this case, with a 200-line input file, we're only looking at 40,000 comparisons (at most).

Run time of the script is real 0m0.177s user 0m0.198s sys 0m0.043s.

Part 2

Part 2 extends part 1 to find 3 entries that sum to 2020 instead.

Reading the input doesn't change in this one so let's look at the search: 

main(_) ->
    Entries = read_input("p1.txt"),
    {X, Y, Z} = find_triple(Entries),
    io:format("answer: ~p: ~p~n", [{X, Y, Z}, X * Y * Z]).

find_triple([X | Entries]) ->
    case find_double(2020-X, Entries) of
	'undefined' -> find_triple(Entries);
	{Y, Z} -> {X, Y, Z}
    end.

find_double(_Total, []) -> 'undefined';
find_double(Total, _) when Total < 0 -> 'undefined';
find_double(Total, [Y | Entries]) when Y >= Total ->
    find_double(Total, Entries);
find_double(Total, [Y | Entries]) ->
    case [Z || Z <- Entries, Y+Z =:= Total] of
	[] -> find_double(Total, Entries);
	[Z] -> {Y, Z}
    end.

Similar in concept to part 1, we decompose the problem. Given the head of the list, X, search the tail of the list for two entries that sum to (2020 - X). If none is found, recurse into find_triple/1 with the tail of the list.

Within find_double/2 we take the head of the list, Y, and iterate through the tail of the list looking for a Z that will satisfy Y + Z = 2020 - X. If none is found, recurse using the tail of the list.

We're pushing into O(n^3) territory which still only puts us around 8,000,000 comparisons which is pretty trivial for CPUs. Indeed, run time is indistinguishable from part 1: real 0m0.175s user 0m0.179s sys 0m0.067s.

Wrap up

Day 1 whet the whistle. Took slightly different approaches to iteration and recursion in each part for fun. Dataset is small enough to not be overly concerned with efficiency of approach, instead focusing on (hopefully) solving the problem in an easy-to-read way.

Advent Of Code 2020

I'll be participating, slowly, in the Advent Of Code and writing about how I used Erlang to solve the problems.

The goal of the code is, hopefully, to be easy to read and reason about.

Not-goals include being the shortest, fastest, or "cleverest". Nothing about the code is "best"; it will represent whatever chunk of time I'm able to offer it.

Subsequent posts will cover a particular day's two-part challenge. Both parts will be their own escripts. As with past years, as the problems get harder and build on previous work, I'll introduce some compiled modules and direct the escript to use them as well.

Posts will follow some basic thought patterns I have, the "final" code, and an annotated walkthrough of the code.

I hope it will be more signal than noise for you!

Problem Writeups

Why the Confederate flag should not be actively flown

From an AP US History Teacher: If you are confused as to why so many Americans are defending the confederate flag, monuments, and statues right now, I put together a quick Q&A, with questions from a hypothetical person with misconceptions and answers from my perspective as an AP U.S. History Teacher:

Q: What did the Confederacy stand for?

A: Rather than interpreting, let's go directly to the words of the Confederacy's Vice President, Alexander Stephens. In his "Cornerstone Speech" on March 21, 1861, he stated "The Constitution… rested upon the equality of races. This was an error. Our new government is founded upon exactly the opposite idea; its foundations are laid, its corner-stone rests, upon the great truth that the negro is not equal to the white man; that slavery subordination to the superior race is his natural and normal condition. This, our new government, is the first, in the history of the world, based upon this great physical, philosophical, and moral truth."

Q: But people keep saying heritage, not hate! They think the purpose of the flags and monuments are to honor confederate soldiers, right?

A: The vast majority of confederate flags flying over government buildings in the south were first put up in the 1960's during the Civil Rights Movement. So for the first hundred years after the Civil War ended, while relatives of those who fought in it were still alive, the confederate flag wasn't much of a symbol at all. But when Martin Luther King, Jr. and John Lewis were marching on Washington to get the Civil Rights Act (1964) and Voting Rights Act (1965) passed, leaders in the south felt compelled to fly confederate flags and put up monuments to honor people who had no living family members and had fought in a war that ended a century ago. Their purpose in doing this was to exhibit their displeasure with black people fighting for basic human rights that were guaranteed to them in the 14th and 15th Amendments but being withheld by racist policies and practices.

Q: But if we take down confederate statues and monuments, how will we teach about and remember the past?

A: Monuments and statues pose little educational relevance, whereas museums, the rightful place for Confederate paraphernalia, can provide more educational opportunities for citizens to learn about our country's history. The Civil War is important to learn about, and will always loom large in social studies curriculum. Removing monuments from public places and putting them in museums also allows us to avoid celebrating and honoring people who believed that tens of millions of black Americans should be legal property.

Q: But my uncle posted a meme that said the Civil War/Confederacy was about state's rights and not slavery?

A: "A state's right to what?" - John Green

Q: Everyone is offended about everything these days. Should we take everything down that offends anyone?

A: The Confederacy literally existed to go against the Constitution, the Declaration of Independence, and the idea that black people are human beings that deserve to live freely. If that doesn't upset or offend you, you are un-American.

Q: Taking these down goes against the First Amendment and freedom of speech, right?

A: No. Anyone can do whatever they want on their private property, on their social media, etc. Taking these down in public, or having private corporations like NASCAR ban them on their properties, has literally nothing to do with the Bill of Rights.

Q: How can people claim to be patriotic while supporting a flag that stood for a group of insurgent failures who tried to permanently destroy America and killed 300,000 Americans in the process?

A: No clue.

Q: So if I made a confederate flag my profile picture, or put a confederate bumper sticker on my car, what am I declaring to my friends, family, and the world?

A: That you support the Confederacy. To recap, the Confederacy stands for: slavery, white supremacy, treason, failure, and a desire to permanently destroy Selective history as it supports white supremacy.

It’s no accident that:

  • You learned about Helen Keller instead of W.E.B, DuBois
  • You learned about the Watts and L.A. Riots, but not Tulsa or Wilmington.
  • You learned that George Washington’s dentures were made from wood, rather than the teeth from slaves.
  • You learned about black ghettos, but not about Black Wall Street.
  • You learned about the New Deal, but not “red lining.”
  • You learned about Tommie Smith’s fist in the air at the 1968 Olympics, but not that he was sent home the next day and stripped of his medals.
  • You learned about “black crime,” but white criminals were never lumped together and discussed in terms of their race.
  • You learned about “states rights” as the cause of the Civil War, but not that slavery was mentioned 80 times in the articles of secession.

Privilege is having history rewritten so that you don’t have to acknowledge uncomfortable facts.

Racism is perpetuated by people who refuse to learn or acknowledge this reality.

You have a choice. - Jim Golden

Setting up call forwarding in KAZOO

With the transition to working from home in full swing, let's look at the ways KAZOO makes it easy to bring your office with you!

From Scratch

Let's say you are a solo business owner who needs to forward your business phone calls to your personal mobile phone. Assuming the business phone number is provisioned for the account already, here's the basic steps to set that up!

Setup the callflow

A callflow in KAZOO is what is executed when a configured phone number, extension, or regexp matches the incoming call. The flow portion will then be a series of actions (like ringing devices, going to voicemail, sending to the carrier, etc) chained together to control how the caller progresses through the call.

Since you want to forward calls from your business number to your mobile, you'll need to use the resources action. The callflow data object would look like: 

{
  "flow": {
    "data": {
      "to_did": "{MOBILE_NUMBER}"
    },
    "module": "resources"
  },
  "name": "forward business to mobile",
  "numbers": [
    "{BUSINESS_NUMBER}"
  ]
}

Simply stated, the resource action's to_did will override the normal action to call the to number with to_did instead. The power here is that the same callflow can be used for many numbers (say multiple businesses you might accept calls for).

The basic API call then becomes: 

curl -H "X-Auth-Token: {API_AUTH_TOKEN}" \
     -X PUT \
     -d '{"data":{"name":"forward business to mobile","numbers":["{BUSINESS_NUMBER}"],"flow":{"module":"resources","data":{"to_did":"{MOBILE_NUMBER}"}}}}'
     https://api.kazoo.domain/v2/accounts/{ACCOUNT_ID}/callflows

Voicemail considerations

With calls forwarded to the carriers in the manner above, your personal voicemail will answer the call if you are unable to at the time. If this is not desirable, you will need to slightly modify how you make this happen.

What you need is to require the callee (you) to press 1 to accept the call before KAZOO will let connect the caller to your mobile phone. If your personal voicemail tries to pick up the call, KAZOO will not continue and will return to the callflow and try the child of the resources action. Since there is no child, the call will be hung up - not ideal!

To setup the required keypress, you'll need to create a call-forwarded device.

Call-Forwarded Device

KAZOO devices can be configured to represent anything from SIP devices to call-forwarded devices, WebRTC, and other types. The other nice benefit is that you can assign the device, via the owner_id property, to your KAZOO user and get calls to ring any of your devices!

To create the call-forwarded device, you only need to setup the call_forward object: 

{
  "call_forward": {
    "enabled": true,
    "number": "{MOBILE_NUMBER}",
    "require_keypress": true
  },
  "name": "WFH device",
  "owner_id": "{USER_ID}"
}

Not strictly required to include owner_id (especially if this is a temporary setup until the office re-opens).

The API command then becomes: 

curl -H "X-Auth-Token: {API_AUTH_TOKEN}" \
     -X PUT \
     -d '{"data":{"name":"WFH device","call_forward":{"enabled":true,"number":"{MOBILE_NUMBER}","require_keypress":true},"owner_id":"{USER_ID}"}}'
     https://api.kazoo.domain/v2/accounts/{ACCOUNT_ID}/devices

The callflow action is then changed to: 

"flow":{
  "module":"device"
  ,"data":{"id":"{WFH_DEVICE_ID}"}
}

Now when your personal voicemail picks up, KAZOO will not connect the caller and will instead go to the child (which currently is missing!). Let's add your business voicemail box.

Call-forwarding plus Voicemail

If you haven't already created a KAZOO voicemail box its a straight-forward process similar to device and callflow creation via API.

Once you have the voicemail box ID you can modify the callflow's flow to look like: 

{
  "flow": {
    "children": {
      "_": {
	"data": {
	  "id": "{VOICEMAIL_BOX_ID}"
	},
	"module": "voicemail"
      }
    },
    "data": {
      "id": "{WFH_DEVICE_ID}"
    },
    "module": "device"
  }
}

Of course now that you have KAZOO voicemail, you can enable voicemail-to-email, transcription (if your cluster supports it), auto-delete from the voicemail box after successfully sending the email, and more.

Configure using the UI

You can also use two of 2600Hz's UI apps, SmartPBX or Advanced Callflows, to achieve the same configurations as the direct API examples above.

Take a walk-through of SmartPBX to see more or jump to the call-forwarding setup.

Customize routing decisions

Sometimes KAZOO callflow actions can't quite encode the flow you would like to achieve, or KAZOO doesn't have access to data sources needed to make routing decisions. Fortunately KAZOO has Pivot to help you take control of call routing when you need more dynamic handling.

The callflow is simple: 

{
  "flow": {
    "children": {
      "_": {
	"data": {
	  "id": "{WFH_CALLFLOW_ID}"
	},
	"module": "callflow"
      }
    },
    "data": {
      "method": "POST",
      "req_format": "kazoo",
      "voice_url": "https://your.http.server/pivot/whatever/language/you/like.ext"
    },
    "module": "pivot"
  },
  "name": "dynamic call control",
  "numbers": [
    "{BUSINESS_NUMBER}"
  ]
}

Now any call to {BUSINESS_NUMBER} will issue an HTTP request to your.http.server. If your server fails to respond, the callflow will continue and run the callflow from above (you would need to remove the {BUSINESS_NUMBER} from the numbers array on that callflow so they don't conflict with the Pivot callflow here).

Your server, in your language of choice, will process the request data, consult any data sources, make any business logic decisions, then send a response with the appropriate callflow 'flow' object. For instance, to have callflow mirror the routing to the call-forwarded device, your PHP script might look like: 

<?php
header('content-type: application/json');

/* Business logic
 * Database lookups
 * Whatever shenanigans
 */
?>
{
  "module":"device"
  ,"data":{"id":"{WFH_DEVICE_ID}"}
}

Wrap-up

In this post we've walked through what API calls and JSON objects would be needed to setup call-forwarding of a phone number (like the business' phone number) to another phone number (like the owner's personal mobile number). Depending on what voicemail box you'd like to answer if the callee is unavailable will determine which path, device or resource, you use to route the caller.

We also briefly introduced the idea of using Pivot to encode custom logic when routing callers to the call-forwarded device (and provide a child action if the Pivot request fails for any reason).

The building blocks exposed in KAZOO's callflow actions are many (~75 at last count) and run the gamut from low-level - collecting touch tones (DTMF) or playing text (TTS) to the caller, or time of day routing - up to more conceptual actions like leaving and checking voicemails, ringing a user's devices, user directories, and so much more.

Have questions? Join our forum, hop on IRC (Freenode #2600hz) to chat, and start an all-in-one install to test things out.

If you have a business and want to engage on using our hosted platform or other offerings, we at 2600Hz are ready to chat (sales@2600hz.com) and help you build it!

Sponsor Me!

Recently learned that I was accepted to Github's beta sponsorship program which allows me to define sponsorship tiers!

https://github.com/sponsors/jamesaimonetti

My hope is that folks that have appreciated my work with KAZOO and help in the forums, documentation, and IRC, might throw a bone or two of thanks my way. If there's a better tier that would get you on board, let me know.

Logging emacs-slack conversations to file

At work, we've been coerced for a few years now to use Slack. At first it wasn't too bad; Slack provided an IRC gateway so irssi remained viable. Then in 2018 they shut down the gateways in the name of "security".

Enter emacs-slack!

As part of my personal initiative to move more of my computing life into Emacs, the IRC gateway closure actually provided me the necessary kick in the pants to move chat from irssi to Emacs.

I'm a simple user and emacs-slack has just worked. I have a few elisp customizations pulled from various sites but for the most part have left emacs-slack to the defaults.

The only thing I missed from irssi was logged chats to my local disk.

Logging chats to disk

My feature was simple - per-team, per-channel, dated files. Basically appending each message received to log/{TEAM}/{CHANNEL}/{YYYY-MM-DD}.log.

I took inspiration from this issue to create a custom message handler (stored in slack-message-custom-notifier) that would log the incoming message to disk: 

(setq slack-log-directory (concat (expand-file-name slack-file-dir)))

(defun mc_/handle-message (message room team)
  (let* ((team-name (slack-team-name team))
	 (room-name (slack-room-name room team))
	 (text (slack-message-to-string message team)))
    (mc_/chat-log team-name room-name text)))

(defun mc_/chat-log (team-name room-name text)
  "Write to log/{TEAM}/{ROOM}/{DATE}.log"
  (let* ((dir slack-log-directory)
	 (today (format-time-string "%Y-%m-%d"))
	 (filename (format "%s%s/%s/%s.log" dir team-name room-name today)))
    (when (not (file-exists-p filename))
      (make-directory (file-name-directory filename) t)
      (write-region "" nil filename)
      )
    (write-region (concat (format-time-string "%H:%M:%S") ": " text "\n") nil filename 'append)))

(setq slack-message-custom-notifier #'mc_/handle-message)

I've posted to /r/emacs with the above to solicit feedback. Hopefully this isn't too far off the mark though! Updates if/when the code is revised.